Add PWA support with offline-first caching (v0.43.1)

- Add web app manifest for standalone installation
- Add service worker with offline-first caching for static assets
- Add network-first caching with fallback for API calls
- Generate PWA icons (192x192, 512x512) from favicon
- Add Apple PWA meta tags for iOS support
- Update rollup config to copy PWA files to dist

Files modified:
- app/web/public/manifest.json: New PWA manifest
- app/web/public/sw.js: New service worker
- app/web/public/icon-192.png: New PWA icon
- app/web/public/icon-512.png: New PWA icon
- app/web/public/index.html: Add manifest link, meta tags, SW registration
- app/web/rollup.config.js: Add PWA files to copy targets
- pkg/version/version: Bump to v0.43.1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude/commands/release.md

@@ -0,0 +1,62 @@
+# Release Command
+
+Review all changes in the repository and create a release with proper commit message, version tag, and push to remotes.
+
+## Argument: $ARGUMENTS
+
+The argument should be one of:
+- `patch` - Bump the patch version (e.g., v0.35.3 -> v0.35.4)
+- `minor` - Bump the minor version and reset patch to 0 (e.g., v0.35.3 -> v0.36.0)
+
+If no argument provided, default to `patch`.
+
+## Steps to perform:
+
+1. **Read the current version** from `pkg/version/version`
+
+2. **Calculate the new version** based on the argument:
+   - Parse the current version (format: vMAJOR.MINOR.PATCH)
+   - If `patch`: increment PATCH by 1
+   - If `minor`: increment MINOR by 1, set PATCH to 0
+
+3. **Update the version file** (`pkg/version/version`) with the new version
+
+4. **Rebuild the embedded web UI** by running:
+   ```
+   ./scripts/update-embedded-web.sh
+   ```
+   This ensures the latest web UI changes are included in the release.
+
+5. **Review changes** using `git status` and `git diff --stat HEAD`
+
+6. **Compose a commit message** following this format:
+   - First line: 72 chars max, imperative mood summary
+   - Blank line
+   - Bullet points describing each significant change
+   - "Files modified:" section listing affected files
+   - Footer with Claude Code attribution
+
+7. **Stage all changes** with `git add -A`
+
+8. **Create the commit** with the composed message
+
+9. **Create a git tag** with the new version (e.g., `v0.36.0`)
+
+10. **Push to remotes** (origin, gitea, and git.mleku.dev) with tags:
+    ```
+    git push origin main --tags
+    git push gitea main --tags
+    GIT_SSH_COMMAND="ssh -i ~/.ssh/gitmlekudev" git push ssh://mleku@git.mleku.dev:2222/mleku/next.orly.dev.git main --tags
+    ```
+
+11. **Deploy to VPS** by running:
+    ```
+    ssh relay.orly.dev 'cd ~/src/next.orly.dev && git stash && git pull origin main && export PATH=$PATH:~/go/bin && CGO_ENABLED=0 go build -o ~/.local/bin/next.orly.dev && sudo systemctl restart orly && ~/.local/bin/next.orly.dev version'
+    ```
+
+12. **Report completion** with the new version and commit hash
+
+## Important:
+- Do NOT push to github remote (only origin and gitea)
+- Always verify the build compiles before committing: `CGO_ENABLED=0 go build -o /dev/null ./...`
+- If build fails, fix issues before proceeding

.claude/settings.local.json

@@ -1,23 +1,13 @@
 {
   "permissions": {
-    "allow": [
-      "Skill(skill-creator)",
-      "Bash(cat:*)",
-      "Bash(python3:*)",
-      "Bash(find:*)",
-      "Skill(nostr-websocket)",
-      "Bash(go build:*)",
-      "Bash(chmod:*)",
-      "Bash(journalctl:*)",
-      "Bash(timeout 5 bash -c 'echo [\"\"REQ\"\",\"\"test123\"\",{\"\"kinds\"\":[1],\"\"limit\"\":1}] | websocat ws://localhost:3334':*)",
-      "Bash(pkill:*)",
-      "Bash(timeout 5 bash:*)",
-      "Bash(md5sum:*)",
-      "Bash(timeout 3 bash -c 'echo [\\\"\"REQ\\\"\",\\\"\"test456\\\"\",{\\\"\"kinds\\\"\":[1],\\\"\"limit\\\"\":10}] | websocat ws://localhost:3334')",
-      "Bash(printf:*)",
-      "Bash(websocat:*)"
-    ],
+    "allow": [],
     "deny": [],
-    "ask": []
-  }
+    "ask": [],
+    "additionalDirectories": [
+      "/home/mleku/smesh",
+      "/home/mleku/Tourmaline"
+    ]
+  },
+  "outputStyle": "Default",
+  "MAX_THINKING_TOKENS": "8000"
 }

.claude/skills/applesauce-core/SKILL.md

@@ -0,0 +1,634 @@
+---
+name: applesauce-core
+description: This skill should be used when working with applesauce-core library for Nostr client development, including event stores, queries, observables, and client utilities. Provides comprehensive knowledge of applesauce patterns for building reactive Nostr applications.
+---
+
+# applesauce-core Skill
+
+This skill provides comprehensive knowledge and patterns for working with applesauce-core, a library that provides reactive utilities and patterns for building Nostr clients.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building reactive Nostr applications
+- Managing event stores and caches
+- Working with observable patterns for Nostr
+- Implementing real-time updates
+- Building timeline and feed views
+- Managing replaceable events
+- Working with profiles and metadata
+- Creating efficient Nostr queries
+
+## Core Concepts
+
+### applesauce-core Overview
+
+applesauce-core provides:
+- **Event stores** - Reactive event caching and management
+- **Queries** - Declarative event querying patterns
+- **Observables** - RxJS-based reactive patterns
+- **Profile helpers** - Profile metadata management
+- **Timeline utilities** - Feed and timeline building
+- **NIP helpers** - NIP-specific utilities
+
+### Installation
+
+```bash
+npm install applesauce-core
+```
+
+### Basic Architecture
+
+applesauce-core is built on reactive principles:
+- Events are stored in reactive stores
+- Queries return observables that update when new events arrive
+- Components subscribe to observables for real-time updates
+
+## Event Store
+
+### Creating an Event Store
+
+```javascript
+import { EventStore } from 'applesauce-core';
+
+// Create event store
+const eventStore = new EventStore();
+
+// Add events
+eventStore.add(event1);
+eventStore.add(event2);
+
+// Add multiple events
+eventStore.addMany([event1, event2, event3]);
+
+// Check if event exists
+const exists = eventStore.has(eventId);
+
+// Get event by ID
+const event = eventStore.get(eventId);
+
+// Remove event
+eventStore.remove(eventId);
+
+// Clear all events
+eventStore.clear();
+```
+
+### Event Store Queries
+
+```javascript
+// Get all events
+const allEvents = eventStore.getAll();
+
+// Get events by filter
+const filtered = eventStore.filter({
+  kinds: [1],
+  authors: [pubkey]
+});
+
+// Get events by author
+const authorEvents = eventStore.getByAuthor(pubkey);
+
+// Get events by kind
+const textNotes = eventStore.getByKind(1);
+```
+
+### Replaceable Events
+
+applesauce-core handles replaceable events automatically:
+
+```javascript
+// For kind 0 (profile), only latest is kept
+eventStore.add(profileEvent1); // stored
+eventStore.add(profileEvent2); // replaces if newer
+
+// For parameterized replaceable (30000-39999)
+eventStore.add(articleEvent); // keyed by author + kind + d-tag
+
+// Get replaceable event
+const profile = eventStore.getReplaceable(0, pubkey);
+const article = eventStore.getReplaceable(30023, pubkey, 'article-slug');
+```
+
+## Queries
+
+### Query Patterns
+
+```javascript
+import { createQuery } from 'applesauce-core';
+
+// Create a query
+const query = createQuery(eventStore, {
+  kinds: [1],
+  limit: 50
+});
+
+// Subscribe to query results
+query.subscribe(events => {
+  console.log('Current events:', events);
+});
+
+// Query updates automatically when new events added
+eventStore.add(newEvent); // Subscribers notified
+```
+
+### Timeline Query
+
+```javascript
+import { TimelineQuery } from 'applesauce-core';
+
+// Create timeline for user's notes
+const timeline = new TimelineQuery(eventStore, {
+  kinds: [1],
+  authors: [userPubkey]
+});
+
+// Get observable of timeline
+const timeline$ = timeline.events$;
+
+// Subscribe
+timeline$.subscribe(events => {
+  // Events sorted by created_at, newest first
+  renderTimeline(events);
+});
+```
+
+### Profile Query
+
+```javascript
+import { ProfileQuery } from 'applesauce-core';
+
+// Query profile metadata
+const profileQuery = new ProfileQuery(eventStore, pubkey);
+
+// Get observable
+const profile$ = profileQuery.profile$;
+
+profile$.subscribe(profile => {
+  if (profile) {
+    console.log('Name:', profile.name);
+    console.log('Picture:', profile.picture);
+  }
+});
+```
+
+## Observables
+
+### Working with RxJS
+
+applesauce-core uses RxJS observables:
+
+```javascript
+import { map, filter, distinctUntilChanged } from 'rxjs/operators';
+
+// Transform query results
+const names$ = profileQuery.profile$.pipe(
+  filter(profile => profile !== null),
+  map(profile => profile.name),
+  distinctUntilChanged()
+);
+
+// Combine multiple observables
+import { combineLatest } from 'rxjs';
+
+const combined$ = combineLatest([
+  timeline$,
+  profile$
+]).pipe(
+  map(([events, profile]) => ({
+    events,
+    authorName: profile?.name
+  }))
+);
+```
+
+### Creating Custom Observables
+
+```javascript
+import { Observable } from 'rxjs';
+
+function createEventObservable(store, filter) {
+  return new Observable(subscriber => {
+    // Initial emit
+    subscriber.next(store.filter(filter));
+
+    // Subscribe to store changes
+    const unsubscribe = store.onChange(() => {
+      subscriber.next(store.filter(filter));
+    });
+
+    // Cleanup
+    return () => unsubscribe();
+  });
+}
+```
+
+## Profile Helpers
+
+### Profile Metadata
+
+```javascript
+import { parseProfile, ProfileContent } from 'applesauce-core';
+
+// Parse kind 0 content
+const profileEvent = await getProfileEvent(pubkey);
+const profile = parseProfile(profileEvent);
+
+// Profile fields
+console.log(profile.name);      // Display name
+console.log(profile.about);     // Bio
+console.log(profile.picture);   // Avatar URL
+console.log(profile.banner);    // Banner image URL
+console.log(profile.nip05);     // NIP-05 identifier
+console.log(profile.lud16);     // Lightning address
+console.log(profile.website);   // Website URL
+```
+
+### Profile Store
+
+```javascript
+import { ProfileStore } from 'applesauce-core';
+
+const profileStore = new ProfileStore(eventStore);
+
+// Get profile observable
+const profile$ = profileStore.getProfile(pubkey);
+
+// Get multiple profiles
+const profiles$ = profileStore.getProfiles([pubkey1, pubkey2]);
+
+// Request profile load (triggers fetch if not cached)
+profileStore.requestProfile(pubkey);
+```
+
+## Timeline Utilities
+
+### Building Feeds
+
+```javascript
+import { Timeline } from 'applesauce-core';
+
+// Create timeline
+const timeline = new Timeline(eventStore);
+
+// Add filter
+timeline.setFilter({
+  kinds: [1, 6],
+  authors: followedPubkeys
+});
+
+// Get events observable
+const events$ = timeline.events$;
+
+// Load more (pagination)
+timeline.loadMore(50);
+
+// Refresh (get latest)
+timeline.refresh();
+```
+
+### Thread Building
+
+```javascript
+import { ThreadBuilder } from 'applesauce-core';
+
+// Build thread from root event
+const thread = new ThreadBuilder(eventStore, rootEventId);
+
+// Get thread observable
+const thread$ = thread.thread$;
+
+thread$.subscribe(threadData => {
+  console.log('Root:', threadData.root);
+  console.log('Replies:', threadData.replies);
+  console.log('Reply count:', threadData.replyCount);
+});
+```
+
+### Reactions and Zaps
+
+```javascript
+import { ReactionStore, ZapStore } from 'applesauce-core';
+
+// Reactions
+const reactionStore = new ReactionStore(eventStore);
+const reactions$ = reactionStore.getReactions(eventId);
+
+reactions$.subscribe(reactions => {
+  console.log('Likes:', reactions.likes);
+  console.log('Custom:', reactions.custom);
+});
+
+// Zaps
+const zapStore = new ZapStore(eventStore);
+const zaps$ = zapStore.getZaps(eventId);
+
+zaps$.subscribe(zaps => {
+  console.log('Total sats:', zaps.totalAmount);
+  console.log('Zap count:', zaps.count);
+});
+```
+
+## NIP Helpers
+
+### NIP-05 Verification
+
+```javascript
+import { verifyNip05 } from 'applesauce-core';
+
+// Verify NIP-05
+const result = await verifyNip05('alice@example.com', expectedPubkey);
+
+if (result.valid) {
+  console.log('NIP-05 verified');
+} else {
+  console.log('Verification failed:', result.error);
+}
+```
+
+### NIP-10 Reply Parsing
+
+```javascript
+import { parseReplyTags } from 'applesauce-core';
+
+// Parse reply structure
+const parsed = parseReplyTags(event);
+
+console.log('Root event:', parsed.root);
+console.log('Reply to:', parsed.reply);
+console.log('Mentions:', parsed.mentions);
+```
+
+### NIP-65 Relay Lists
+
+```javascript
+import { parseRelayList } from 'applesauce-core';
+
+// Parse relay list event (kind 10002)
+const relays = parseRelayList(relayListEvent);
+
+console.log('Read relays:', relays.read);
+console.log('Write relays:', relays.write);
+```
+
+## Integration with nostr-tools
+
+### Using with SimplePool
+
+```javascript
+import { SimplePool } from 'nostr-tools';
+import { EventStore } from 'applesauce-core';
+
+const pool = new SimplePool();
+const eventStore = new EventStore();
+
+// Load events into store
+pool.subscribeMany(relays, [filter], {
+  onevent(event) {
+    eventStore.add(event);
+  }
+});
+
+// Query store reactively
+const timeline$ = createTimelineQuery(eventStore, filter);
+```
+
+### Publishing Events
+
+```javascript
+import { finalizeEvent } from 'nostr-tools';
+
+// Create event
+const event = finalizeEvent({
+  kind: 1,
+  content: 'Hello!',
+  created_at: Math.floor(Date.now() / 1000),
+  tags: []
+}, secretKey);
+
+// Add to local store immediately (optimistic update)
+eventStore.add(event);
+
+// Publish to relays
+await pool.publish(relays, event);
+```
+
+## Svelte Integration
+
+### Using in Svelte Components
+
+```svelte
+<script>
+  import { onMount, onDestroy } from 'svelte';
+  import { EventStore, TimelineQuery } from 'applesauce-core';
+
+  export let pubkey;
+
+  const eventStore = new EventStore();
+  let events = [];
+  let subscription;
+
+  onMount(() => {
+    const timeline = new TimelineQuery(eventStore, {
+      kinds: [1],
+      authors: [pubkey]
+    });
+
+    subscription = timeline.events$.subscribe(e => {
+      events = e;
+    });
+  });
+
+  onDestroy(() => {
+    subscription?.unsubscribe();
+  });
+</script>
+
+{#each events as event}
+  <div class="event">
+    {event.content}
+  </div>
+{/each}
+```
+
+### Svelte Store Adapter
+
+```javascript
+import { readable } from 'svelte/store';
+
+// Convert RxJS observable to Svelte store
+function fromObservable(observable, initialValue) {
+  return readable(initialValue, set => {
+    const subscription = observable.subscribe(set);
+    return () => subscription.unsubscribe();
+  });
+}
+
+// Usage
+const events$ = timeline.events$;
+const eventsStore = fromObservable(events$, []);
+```
+
+```svelte
+<script>
+  import { eventsStore } from './stores.js';
+</script>
+
+{#each $eventsStore as event}
+  <div>{event.content}</div>
+{/each}
+```
+
+## Best Practices
+
+### Store Management
+
+1. **Single store instance** - Use one EventStore per app
+2. **Clear stale data** - Implement cache limits
+3. **Handle replaceable events** - Let store manage deduplication
+4. **Unsubscribe** - Clean up subscriptions on component destroy
+
+### Query Optimization
+
+1. **Use specific filters** - Narrow queries perform better
+2. **Limit results** - Use limit for initial loads
+3. **Cache queries** - Reuse query instances
+4. **Debounce updates** - Throttle rapid changes
+
+### Memory Management
+
+1. **Limit store size** - Implement LRU or time-based eviction
+2. **Clean up observables** - Unsubscribe when done
+3. **Use weak references** - For profile caches
+4. **Paginate large feeds** - Don't load everything at once
+
+### Reactive Patterns
+
+1. **Prefer observables** - Over imperative queries
+2. **Use operators** - Transform data with RxJS
+3. **Combine streams** - For complex views
+4. **Handle loading states** - Show placeholders
+
+## Common Patterns
+
+### Event Deduplication
+
+```javascript
+// EventStore handles deduplication automatically
+eventStore.add(event1);
+eventStore.add(event1); // No duplicate
+
+// For manual deduplication
+const seen = new Set();
+events.filter(e => {
+  if (seen.has(e.id)) return false;
+  seen.add(e.id);
+  return true;
+});
+```
+
+### Optimistic Updates
+
+```javascript
+async function publishNote(content) {
+  // Create event
+  const event = await createEvent(content);
+
+  // Add to store immediately (optimistic)
+  eventStore.add(event);
+
+  try {
+    // Publish to relays
+    await pool.publish(relays, event);
+  } catch (error) {
+    // Remove on failure
+    eventStore.remove(event.id);
+    throw error;
+  }
+}
+```
+
+### Loading States
+
+```javascript
+import { BehaviorSubject, combineLatest } from 'rxjs';
+
+const loading$ = new BehaviorSubject(true);
+const events$ = timeline.events$;
+
+const state$ = combineLatest([loading$, events$]).pipe(
+  map(([loading, events]) => ({
+    loading,
+    events,
+    empty: !loading && events.length === 0
+  }))
+);
+
+// Start loading
+loading$.next(true);
+await loadEvents();
+loading$.next(false);
+```
+
+### Infinite Scroll
+
+```javascript
+function createInfiniteScroll(timeline, pageSize = 50) {
+  let loading = false;
+
+  async function loadMore() {
+    if (loading) return;
+
+    loading = true;
+    await timeline.loadMore(pageSize);
+    loading = false;
+  }
+
+  function onScroll(event) {
+    const { scrollTop, scrollHeight, clientHeight } = event.target;
+    if (scrollHeight - scrollTop <= clientHeight * 1.5) {
+      loadMore();
+    }
+  }
+
+  return { loadMore, onScroll };
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Events not updating:**
+- Check subscription is active
+- Verify events are being added to store
+- Ensure filter matches events
+
+**Memory growing:**
+- Implement store size limits
+- Clean up subscriptions
+- Use weak references where appropriate
+
+**Slow queries:**
+- Add indexes for common queries
+- Use more specific filters
+- Implement pagination
+
+**Stale data:**
+- Implement refresh mechanisms
+- Set up real-time subscriptions
+- Handle replaceable event updates
+
+## References
+
+- **applesauce GitHub**: https://github.com/hzrd149/applesauce
+- **RxJS Documentation**: https://rxjs.dev
+- **nostr-tools**: https://github.com/nbd-wtf/nostr-tools
+- **Nostr Protocol**: https://github.com/nostr-protocol/nostr
+
+## Related Skills
+
+- **nostr-tools** - Lower-level Nostr operations
+- **applesauce-signers** - Event signing abstractions
+- **svelte** - Building reactive UIs
+- **nostr** - Nostr protocol fundamentals

.claude/skills/applesauce-signers/SKILL.md

@@ -0,0 +1,757 @@
+---
+name: applesauce-signers
+description: This skill should be used when working with applesauce-signers library for Nostr event signing, including NIP-07 browser extensions, NIP-46 remote signing, and custom signer implementations. Provides comprehensive knowledge of signing patterns and signer abstractions.
+---
+
+# applesauce-signers Skill
+
+This skill provides comprehensive knowledge and patterns for working with applesauce-signers, a library that provides signing abstractions for Nostr applications.
+
+## When to Use This Skill
+
+Use this skill when:
+- Implementing event signing in Nostr applications
+- Integrating with NIP-07 browser extensions
+- Working with NIP-46 remote signers
+- Building custom signer implementations
+- Managing signing sessions
+- Handling signing requests and permissions
+- Implementing multi-signer support
+
+## Core Concepts
+
+### applesauce-signers Overview
+
+applesauce-signers provides:
+- **Signer abstraction** - Unified interface for different signers
+- **NIP-07 integration** - Browser extension support
+- **NIP-46 support** - Remote signing (Nostr Connect)
+- **Simple signers** - Direct key signing
+- **Permission handling** - Manage signing requests
+- **Observable patterns** - Reactive signing states
+
+### Installation
+
+```bash
+npm install applesauce-signers
+```
+
+### Signer Interface
+
+All signers implement a common interface:
+
+```typescript
+interface Signer {
+  // Get public key
+  getPublicKey(): Promise<string>;
+
+  // Sign event
+  signEvent(event: UnsignedEvent): Promise<SignedEvent>;
+
+  // Encrypt (NIP-04)
+  nip04Encrypt?(pubkey: string, plaintext: string): Promise<string>;
+  nip04Decrypt?(pubkey: string, ciphertext: string): Promise<string>;
+
+  // Encrypt (NIP-44)
+  nip44Encrypt?(pubkey: string, plaintext: string): Promise<string>;
+  nip44Decrypt?(pubkey: string, ciphertext: string): Promise<string>;
+}
+```
+
+## Simple Signer
+
+### Using Secret Key
+
+```javascript
+import { SimpleSigner } from 'applesauce-signers';
+import { generateSecretKey } from 'nostr-tools';
+
+// Create signer with existing key
+const signer = new SimpleSigner(secretKey);
+
+// Or generate new key
+const newSecretKey = generateSecretKey();
+const newSigner = new SimpleSigner(newSecretKey);
+
+// Get public key
+const pubkey = await signer.getPublicKey();
+
+// Sign event
+const unsignedEvent = {
+  kind: 1,
+  content: 'Hello Nostr!',
+  created_at: Math.floor(Date.now() / 1000),
+  tags: []
+};
+
+const signedEvent = await signer.signEvent(unsignedEvent);
+```
+
+### NIP-04 Encryption
+
+```javascript
+// Encrypt message
+const ciphertext = await signer.nip04Encrypt(
+  recipientPubkey,
+  'Secret message'
+);
+
+// Decrypt message
+const plaintext = await signer.nip04Decrypt(
+  senderPubkey,
+  ciphertext
+);
+```
+
+### NIP-44 Encryption
+
+```javascript
+// Encrypt with NIP-44 (preferred)
+const ciphertext = await signer.nip44Encrypt(
+  recipientPubkey,
+  'Secret message'
+);
+
+// Decrypt
+const plaintext = await signer.nip44Decrypt(
+  senderPubkey,
+  ciphertext
+);
+```
+
+## NIP-07 Signer
+
+### Browser Extension Integration
+
+```javascript
+import { Nip07Signer } from 'applesauce-signers';
+
+// Check if extension is available
+if (window.nostr) {
+  const signer = new Nip07Signer();
+
+  // Get public key (may prompt user)
+  const pubkey = await signer.getPublicKey();
+
+  // Sign event (prompts user)
+  const signedEvent = await signer.signEvent(unsignedEvent);
+}
+```
+
+### Handling Extension Availability
+
+```javascript
+function getAvailableSigner() {
+  if (typeof window !== 'undefined' && window.nostr) {
+    return new Nip07Signer();
+  }
+  return null;
+}
+
+// Wait for extension to load
+async function waitForExtension(timeout = 3000) {
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    if (window.nostr) {
+      return new Nip07Signer();
+    }
+    await new Promise(r => setTimeout(r, 100));
+  }
+
+  return null;
+}
+```
+
+### Extension Permissions
+
+```javascript
+// Some extensions support granular permissions
+const signer = new Nip07Signer();
+
+// Request specific permissions
+try {
+  // This varies by extension
+  await window.nostr.enable();
+} catch (error) {
+  console.log('User denied permission');
+}
+```
+
+## NIP-46 Remote Signer
+
+### Nostr Connect
+
+```javascript
+import { Nip46Signer } from 'applesauce-signers';
+
+// Create remote signer
+const signer = new Nip46Signer({
+  // Remote signer's pubkey
+  remotePubkey: signerPubkey,
+
+  // Relays for communication
+  relays: ['wss://relay.example.com'],
+
+  // Local secret key for encryption
+  localSecretKey: localSecretKey,
+
+  // Optional: custom client name
+  clientName: 'My Nostr App'
+});
+
+// Connect to remote signer
+await signer.connect();
+
+// Get public key
+const pubkey = await signer.getPublicKey();
+
+// Sign event
+const signedEvent = await signer.signEvent(unsignedEvent);
+
+// Disconnect when done
+signer.disconnect();
+```
+
+### Connection URL
+
+```javascript
+// Parse nostrconnect:// URL
+function parseNostrConnectUrl(url) {
+  const parsed = new URL(url);
+
+  return {
+    pubkey: parsed.pathname.replace('//', ''),
+    relay: parsed.searchParams.get('relay'),
+    secret: parsed.searchParams.get('secret')
+  };
+}
+
+// Create signer from URL
+const { pubkey, relay, secret } = parseNostrConnectUrl(connectUrl);
+
+const signer = new Nip46Signer({
+  remotePubkey: pubkey,
+  relays: [relay],
+  localSecretKey: generateSecretKey(),
+  secret: secret
+});
+```
+
+### Bunker URL
+
+```javascript
+// Parse bunker:// URL (NIP-46)
+function parseBunkerUrl(url) {
+  const parsed = new URL(url);
+
+  return {
+    pubkey: parsed.pathname.replace('//', ''),
+    relays: parsed.searchParams.getAll('relay'),
+    secret: parsed.searchParams.get('secret')
+  };
+}
+
+const { pubkey, relays, secret } = parseBunkerUrl(bunkerUrl);
+```
+
+## Signer Management
+
+### Signer Store
+
+```javascript
+import { SignerStore } from 'applesauce-signers';
+
+const signerStore = new SignerStore();
+
+// Set active signer
+signerStore.setSigner(signer);
+
+// Get active signer
+const activeSigner = signerStore.getSigner();
+
+// Clear signer (logout)
+signerStore.clearSigner();
+
+// Observable for signer changes
+signerStore.signer$.subscribe(signer => {
+  if (signer) {
+    console.log('Logged in');
+  } else {
+    console.log('Logged out');
+  }
+});
+```
+
+### Multi-Account Support
+
+```javascript
+class AccountManager {
+  constructor() {
+    this.accounts = new Map();
+    this.activeAccount = null;
+  }
+
+  addAccount(pubkey, signer) {
+    this.accounts.set(pubkey, signer);
+  }
+
+  removeAccount(pubkey) {
+    this.accounts.delete(pubkey);
+    if (this.activeAccount === pubkey) {
+      this.activeAccount = null;
+    }
+  }
+
+  switchAccount(pubkey) {
+    if (this.accounts.has(pubkey)) {
+      this.activeAccount = pubkey;
+      return this.accounts.get(pubkey);
+    }
+    return null;
+  }
+
+  getActiveSigner() {
+    return this.activeAccount
+      ? this.accounts.get(this.activeAccount)
+      : null;
+  }
+}
+```
+
+## Custom Signers
+
+### Implementing a Custom Signer
+
+```javascript
+class CustomSigner {
+  constructor(options) {
+    this.options = options;
+  }
+
+  async getPublicKey() {
+    // Return public key
+    return this.options.pubkey;
+  }
+
+  async signEvent(event) {
+    // Implement signing logic
+    // Could call external API, hardware wallet, etc.
+
+    const signedEvent = await this.externalSign(event);
+    return signedEvent;
+  }
+
+  async nip04Encrypt(pubkey, plaintext) {
+    // Implement NIP-04 encryption
+    throw new Error('NIP-04 not supported');
+  }
+
+  async nip04Decrypt(pubkey, ciphertext) {
+    throw new Error('NIP-04 not supported');
+  }
+
+  async nip44Encrypt(pubkey, plaintext) {
+    // Implement NIP-44 encryption
+    throw new Error('NIP-44 not supported');
+  }
+
+  async nip44Decrypt(pubkey, ciphertext) {
+    throw new Error('NIP-44 not supported');
+  }
+}
+```
+
+### Hardware Wallet Signer
+
+```javascript
+class HardwareWalletSigner {
+  constructor(devicePath) {
+    this.devicePath = devicePath;
+  }
+
+  async connect() {
+    // Connect to hardware device
+    this.device = await connectToDevice(this.devicePath);
+  }
+
+  async getPublicKey() {
+    // Get public key from device
+    return await this.device.getNostrPubkey();
+  }
+
+  async signEvent(event) {
+    // Sign on device (user confirms on device)
+    const signature = await this.device.signNostrEvent(event);
+
+    return {
+      ...event,
+      pubkey: await this.getPublicKey(),
+      id: getEventHash(event),
+      sig: signature
+    };
+  }
+}
+```
+
+### Read-Only Signer
+
+```javascript
+class ReadOnlySigner {
+  constructor(pubkey) {
+    this.pubkey = pubkey;
+  }
+
+  async getPublicKey() {
+    return this.pubkey;
+  }
+
+  async signEvent(event) {
+    throw new Error('Read-only mode: cannot sign events');
+  }
+
+  async nip04Encrypt(pubkey, plaintext) {
+    throw new Error('Read-only mode: cannot encrypt');
+  }
+
+  async nip04Decrypt(pubkey, ciphertext) {
+    throw new Error('Read-only mode: cannot decrypt');
+  }
+}
+```
+
+## Signing Utilities
+
+### Event Creation Helper
+
+```javascript
+async function createAndSignEvent(signer, template) {
+  const pubkey = await signer.getPublicKey();
+
+  const event = {
+    ...template,
+    pubkey,
+    created_at: template.created_at || Math.floor(Date.now() / 1000)
+  };
+
+  return await signer.signEvent(event);
+}
+
+// Usage
+const signedNote = await createAndSignEvent(signer, {
+  kind: 1,
+  content: 'Hello!',
+  tags: []
+});
+```
+
+### Batch Signing
+
+```javascript
+async function signEvents(signer, events) {
+  const signed = [];
+
+  for (const event of events) {
+    const signedEvent = await signer.signEvent(event);
+    signed.push(signedEvent);
+  }
+
+  return signed;
+}
+
+// With parallelization (if signer supports)
+async function signEventsParallel(signer, events) {
+  return Promise.all(
+    events.map(event => signer.signEvent(event))
+  );
+}
+```
+
+## Svelte Integration
+
+### Signer Context
+
+```svelte
+<!-- SignerProvider.svelte -->
+<script>
+  import { setContext } from 'svelte';
+  import { writable } from 'svelte/store';
+
+  const signer = writable(null);
+
+  setContext('signer', {
+    signer,
+    setSigner: (s) => signer.set(s),
+    clearSigner: () => signer.set(null)
+  });
+</script>
+
+<slot />
+```
+
+```svelte
+<!-- Component using signer -->
+<script>
+  import { getContext } from 'svelte';
+
+  const { signer } = getContext('signer');
+
+  async function publishNote(content) {
+    if (!$signer) {
+      alert('Please login first');
+      return;
+    }
+
+    const event = await $signer.signEvent({
+      kind: 1,
+      content,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: []
+    });
+
+    // Publish event...
+  }
+</script>
+```
+
+### Login Component
+
+```svelte
+<script>
+  import { getContext } from 'svelte';
+  import { Nip07Signer, SimpleSigner } from 'applesauce-signers';
+
+  const { setSigner, clearSigner, signer } = getContext('signer');
+
+  let nsec = '';
+
+  async function loginWithExtension() {
+    if (window.nostr) {
+      setSigner(new Nip07Signer());
+    } else {
+      alert('No extension found');
+    }
+  }
+
+  function loginWithNsec() {
+    try {
+      const decoded = nip19.decode(nsec);
+      if (decoded.type === 'nsec') {
+        setSigner(new SimpleSigner(decoded.data));
+        nsec = '';
+      }
+    } catch (e) {
+      alert('Invalid nsec');
+    }
+  }
+
+  function logout() {
+    clearSigner();
+  }
+</script>
+
+{#if $signer}
+  <button on:click={logout}>Logout</button>
+{:else}
+  <button on:click={loginWithExtension}>
+    Login with Extension
+  </button>
+
+  <div>
+    <input
+      type="password"
+      bind:value={nsec}
+      placeholder="nsec..."
+    />
+    <button on:click={loginWithNsec}>
+      Login with Key
+    </button>
+  </div>
+{/if}
+```
+
+## Best Practices
+
+### Security
+
+1. **Never store secret keys in plain text** - Use secure storage
+2. **Prefer NIP-07** - Let extensions manage keys
+3. **Clear keys on logout** - Don't leave in memory
+4. **Validate before signing** - Check event content
+
+### User Experience
+
+1. **Show signing status** - Loading states
+2. **Handle rejections gracefully** - User may cancel
+3. **Provide fallbacks** - Multiple login options
+4. **Remember preferences** - Store signer type
+
+### Error Handling
+
+```javascript
+async function safeSign(signer, event) {
+  try {
+    return await signer.signEvent(event);
+  } catch (error) {
+    if (error.message.includes('rejected')) {
+      console.log('User rejected signing');
+      return null;
+    }
+    if (error.message.includes('timeout')) {
+      console.log('Signing timed out');
+      return null;
+    }
+    throw error;
+  }
+}
+```
+
+### Permission Checking
+
+```javascript
+function hasEncryptionSupport(signer) {
+  return typeof signer.nip04Encrypt === 'function' ||
+         typeof signer.nip44Encrypt === 'function';
+}
+
+function getEncryptionMethod(signer) {
+  // Prefer NIP-44
+  if (typeof signer.nip44Encrypt === 'function') {
+    return 'nip44';
+  }
+  if (typeof signer.nip04Encrypt === 'function') {
+    return 'nip04';
+  }
+  return null;
+}
+```
+
+## Common Patterns
+
+### Signer Detection
+
+```javascript
+async function detectSigners() {
+  const available = [];
+
+  // Check NIP-07
+  if (typeof window !== 'undefined' && window.nostr) {
+    available.push({
+      type: 'nip07',
+      name: 'Browser Extension',
+      create: () => new Nip07Signer()
+    });
+  }
+
+  // Check stored credentials
+  const storedKey = localStorage.getItem('nsec');
+  if (storedKey) {
+    available.push({
+      type: 'stored',
+      name: 'Saved Key',
+      create: () => new SimpleSigner(storedKey)
+    });
+  }
+
+  return available;
+}
+```
+
+### Auto-Reconnect for NIP-46
+
+```javascript
+class ReconnectingNip46Signer {
+  constructor(options) {
+    this.options = options;
+    this.signer = null;
+  }
+
+  async connect() {
+    this.signer = new Nip46Signer(this.options);
+    await this.signer.connect();
+  }
+
+  async signEvent(event) {
+    try {
+      return await this.signer.signEvent(event);
+    } catch (error) {
+      if (error.message.includes('disconnected')) {
+        await this.connect();
+        return await this.signer.signEvent(event);
+      }
+      throw error;
+    }
+  }
+}
+```
+
+### Signer Type Persistence
+
+```javascript
+const SIGNER_KEY = 'nostr_signer_type';
+
+function saveSigner(type, data) {
+  localStorage.setItem(SIGNER_KEY, JSON.stringify({ type, data }));
+}
+
+async function restoreSigner() {
+  const saved = localStorage.getItem(SIGNER_KEY);
+  if (!saved) return null;
+
+  const { type, data } = JSON.parse(saved);
+
+  switch (type) {
+    case 'nip07':
+      if (window.nostr) {
+        return new Nip07Signer();
+      }
+      break;
+    case 'simple':
+      // Don't store secret keys!
+      break;
+    case 'nip46':
+      const signer = new Nip46Signer(data);
+      await signer.connect();
+      return signer;
+  }
+
+  return null;
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Extension not detected:**
+- Wait for page load
+- Check window.nostr exists
+- Verify extension is enabled
+
+**Signing rejected:**
+- User cancelled in extension
+- Handle gracefully with error message
+
+**NIP-46 connection fails:**
+- Check relay is accessible
+- Verify remote signer is online
+- Check secret matches
+
+**Encryption not supported:**
+- Check signer has encrypt methods
+- Fall back to alternative method
+- Show user appropriate error
+
+## References
+
+- **applesauce GitHub**: https://github.com/hzrd149/applesauce
+- **NIP-07 Specification**: https://github.com/nostr-protocol/nips/blob/master/07.md
+- **NIP-46 Specification**: https://github.com/nostr-protocol/nips/blob/master/46.md
+- **nostr-tools**: https://github.com/nbd-wtf/nostr-tools
+
+## Related Skills
+
+- **nostr-tools** - Event creation and signing utilities
+- **applesauce-core** - Event stores and queries
+- **nostr** - Nostr protocol fundamentals
+- **svelte** - Building Nostr UIs

.claude/skills/cypher/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: cypher
+description: This skill should be used when writing, debugging, or discussing Neo4j Cypher queries. Provides comprehensive knowledge of Cypher syntax, query patterns, performance optimization, and common mistakes. Particularly useful for translating between domain models and graph queries.
+---
+
+# Neo4j Cypher Query Language
+
+## Purpose
+
+This skill provides expert-level guidance for writing Neo4j Cypher queries, including syntax, patterns, performance optimization, and common pitfalls. It is particularly tuned for the patterns used in this ORLY Nostr relay codebase.
+
+## When to Use
+
+Activate this skill when:
+- Writing Cypher queries for Neo4j
+- Debugging Cypher syntax errors
+- Optimizing query performance
+- Translating Nostr filter queries to Cypher
+- Working with graph relationships and traversals
+- Creating or modifying schema (indexes, constraints)
+
+## Core Cypher Syntax
+
+### Clause Order (CRITICAL)
+
+Cypher requires clauses in a specific order. Violating this causes syntax errors:
+
+```cypher
+// CORRECT order of clauses
+MATCH (n:Label)           // 1. Pattern matching
+WHERE n.prop = value      // 2. Filtering
+WITH n, count(*) AS cnt   // 3. Intermediate results (resets scope)
+OPTIONAL MATCH (n)-[r]-() // 4. Optional patterns
+CREATE (m:NewNode)        // 5. Node/relationship creation
+SET n.prop = value        // 6. Property updates
+DELETE r                  // 7. Deletions
+RETURN n.prop AS result   // 8. Return clause
+ORDER BY result DESC      // 9. Ordering
+SKIP 10 LIMIT 20          // 10. Pagination
+```
+
+### The WITH Clause (CRITICAL)
+
+The `WITH` clause is required to transition between certain operations:
+
+**Rule: Cannot use MATCH after CREATE without WITH**
+
+```cypher
+// WRONG - MATCH after CREATE without WITH
+CREATE (e:Event {id: $id})
+MATCH (ref:Event {id: $refId})  // ERROR!
+CREATE (e)-[:REFERENCES]->(ref)
+
+// CORRECT - Use WITH to carry variables forward
+CREATE (e:Event {id: $id})
+WITH e
+MATCH (ref:Event {id: $refId})
+CREATE (e)-[:REFERENCES]->(ref)
+```
+
+**Rule: WITH resets the scope**
+
+Variables not included in WITH are no longer accessible:
+
+```cypher
+// WRONG - 'a' is lost after WITH
+MATCH (a:Author), (e:Event)
+WITH e
+WHERE a.pubkey = $pubkey  // ERROR: 'a' not defined
+
+// CORRECT - Include all needed variables
+MATCH (a:Author), (e:Event)
+WITH a, e
+WHERE a.pubkey = $pubkey
+```
+
+### Node and Relationship Patterns
+
+```cypher
+// Nodes
+(n)                     // Anonymous node
+(n:Label)               // Labeled node
+(n:Label {prop: value}) // Node with properties
+(n:Label:OtherLabel)    // Multiple labels
+
+// Relationships
+-[r]->                  // Directed, anonymous
+-[r:TYPE]->             // Typed relationship
+-[r:TYPE {prop: value}]-> // With properties
+-[r:TYPE|OTHER]->       // Multiple types (OR)
+-[*1..3]->              // Variable length (1 to 3 hops)
+-[*]->                  // Any number of hops
+```
+
+### MERGE vs CREATE
+
+**CREATE**: Always creates new nodes/relationships (may create duplicates)
+
+```cypher
+CREATE (n:Event {id: $id})  // Creates even if id exists
+```
+
+**MERGE**: Finds or creates (idempotent)
+
+```cypher
+MERGE (n:Event {id: $id})   // Finds existing or creates new
+ON CREATE SET n.created = timestamp()
+ON MATCH SET n.accessed = timestamp()
+```
+
+**Best Practice**: Use MERGE for reference nodes, CREATE for unique events
+
+```cypher
+// Reference nodes - use MERGE (idempotent)
+MERGE (author:Author {pubkey: $pubkey})
+
+// Unique events - use CREATE (after checking existence)
+CREATE (e:Event {id: $eventId, ...})
+```
+
+### OPTIONAL MATCH
+
+Returns NULL for non-matching patterns (like LEFT JOIN):
+
+```cypher
+// Find events, with or without tags
+MATCH (e:Event)
+OPTIONAL MATCH (e)-[:TAGGED_WITH]->(t:Tag)
+RETURN e.id, collect(t.value) AS tags
+```
+
+### Conditional Creation with FOREACH
+
+To conditionally create relationships:
+
+```cypher
+// FOREACH trick for conditional operations
+OPTIONAL MATCH (ref:Event {id: $refId})
+FOREACH (ignoreMe IN CASE WHEN ref IS NOT NULL THEN [1] ELSE [] END |
+  CREATE (e)-[:REFERENCES]->(ref)
+)
+```
+
+### Aggregation Functions
+
+```cypher
+count(*)              // Count all rows
+count(n)              // Count non-null values
+count(DISTINCT n)     // Count unique values
+collect(n)            // Collect into list
+collect(DISTINCT n)   // Collect unique values
+sum(n.value)          // Sum values
+avg(n.value)          // Average
+min(n.value), max(n.value)  // Min/max
+```
+
+### String Operations
+
+```cypher
+// String matching
+WHERE n.name STARTS WITH 'prefix'
+WHERE n.name ENDS WITH 'suffix'
+WHERE n.name CONTAINS 'substring'
+WHERE n.name =~ 'regex.*pattern'  // Regex
+
+// String functions
+toLower(str), toUpper(str)
+trim(str), ltrim(str), rtrim(str)
+substring(str, start, length)
+replace(str, search, replacement)
+```
+
+### List Operations
+
+```cypher
+// IN clause
+WHERE n.kind IN [1, 7, 30023]
+WHERE n.pubkey IN $pubkeyList
+
+// List comprehension
+[x IN list WHERE x > 0 | x * 2]
+
+// UNWIND - expand list into rows
+UNWIND $pubkeys AS pubkey
+MERGE (u:User {pubkey: pubkey})
+```
+
+### Parameters
+
+Always use parameters for values (security + performance):
+
+```cypher
+// CORRECT - parameterized
+MATCH (e:Event {id: $eventId})
+WHERE e.kind IN $kinds
+
+// WRONG - string interpolation (SQL injection risk!)
+MATCH (e:Event {id: '" + eventId + "'})
+```
+
+## Schema Management
+
+### Constraints
+
+```cypher
+// Uniqueness constraint (also creates index)
+CREATE CONSTRAINT event_id_unique IF NOT EXISTS
+FOR (e:Event) REQUIRE e.id IS UNIQUE
+
+// Composite uniqueness
+CREATE CONSTRAINT card_unique IF NOT EXISTS
+FOR (c:Card) REQUIRE (c.customer_id, c.observee_pubkey) IS UNIQUE
+
+// Drop constraint
+DROP CONSTRAINT event_id_unique IF EXISTS
+```
+
+### Indexes
+
+```cypher
+// Single property index
+CREATE INDEX event_kind IF NOT EXISTS FOR (e:Event) ON (e.kind)
+
+// Composite index
+CREATE INDEX event_kind_created IF NOT EXISTS
+FOR (e:Event) ON (e.kind, e.created_at)
+
+// Drop index
+DROP INDEX event_kind IF EXISTS
+```
+
+## Common Query Patterns
+
+### Find with Filter
+
+```cypher
+// Multiple conditions with OR
+MATCH (e:Event)
+WHERE e.kind IN $kinds
+  AND (e.id = $id1 OR e.id = $id2)
+  AND e.created_at >= $since
+RETURN e
+ORDER BY e.created_at DESC
+LIMIT $limit
+```
+
+### Graph Traversal
+
+```cypher
+// Find events by author
+MATCH (e:Event)-[:AUTHORED_BY]->(a:Author {pubkey: $pubkey})
+RETURN e
+
+// Find followers of a user
+MATCH (follower:NostrUser)-[:FOLLOWS]->(user:NostrUser {pubkey: $pubkey})
+RETURN follower.pubkey
+
+// Find mutual follows (friends)
+MATCH (a:NostrUser {pubkey: $pubkeyA})-[:FOLLOWS]->(b:NostrUser)
+WHERE (b)-[:FOLLOWS]->(a)
+RETURN b.pubkey AS mutual_friend
+```
+
+### Upsert Pattern
+
+```cypher
+MERGE (n:Node {key: $key})
+ON CREATE SET
+  n.created_at = timestamp(),
+  n.value = $value
+ON MATCH SET
+  n.updated_at = timestamp(),
+  n.value = $value
+RETURN n
+```
+
+### Batch Processing with UNWIND
+
+```cypher
+// Create multiple nodes from list
+UNWIND $items AS item
+CREATE (n:Node {id: item.id, value: item.value})
+
+// Create relationships from list
+UNWIND $follows AS followed_pubkey
+MERGE (followed:NostrUser {pubkey: followed_pubkey})
+MERGE (author)-[:FOLLOWS]->(followed)
+```
+
+## Performance Optimization
+
+### Index Usage
+
+1. **Start with indexed properties** - Begin MATCH with most selective indexed field
+2. **Use composite indexes** - For queries filtering on multiple properties
+3. **Profile queries** - Use `PROFILE` prefix to see execution plan
+
+```cypher
+PROFILE MATCH (e:Event {kind: 1})
+WHERE e.created_at > $since
+RETURN e LIMIT 100
+```
+
+### Query Optimization Tips
+
+1. **Filter early** - Put WHERE conditions close to MATCH
+2. **Limit early** - Use LIMIT as early as possible
+3. **Avoid Cartesian products** - Connect patterns or use WITH
+4. **Use parameters** - Enables query plan caching
+
+```cypher
+// GOOD - Filter and limit early
+MATCH (e:Event)
+WHERE e.kind IN $kinds AND e.created_at >= $since
+WITH e ORDER BY e.created_at DESC LIMIT 100
+OPTIONAL MATCH (e)-[:TAGGED_WITH]->(t:Tag)
+RETURN e, collect(t)
+
+// BAD - Late filtering
+MATCH (e:Event), (t:Tag)
+WHERE e.kind IN $kinds
+RETURN e, t LIMIT 100
+```
+
+## Reference Materials
+
+For detailed information, consult the reference files:
+
+- **references/syntax-reference.md** - Complete Cypher syntax guide with all clause types, operators, and functions
+- **references/common-patterns.md** - Project-specific patterns for ORLY Nostr relay including event storage, tag queries, and social graph traversals
+- **references/common-mistakes.md** - Frequent Cypher errors and how to avoid them
+
+## ORLY-Specific Patterns
+
+This codebase uses these specific Cypher patterns:
+
+### Event Storage Pattern
+
+```cypher
+// Create event with author relationship
+MERGE (a:Author {pubkey: $pubkey})
+CREATE (e:Event {
+  id: $eventId,
+  serial: $serial,
+  kind: $kind,
+  created_at: $createdAt,
+  content: $content,
+  sig: $sig,
+  pubkey: $pubkey,
+  tags: $tags
+})
+CREATE (e)-[:AUTHORED_BY]->(a)
+```
+
+### Tag Query Pattern
+
+```cypher
+// Query events by tag (Nostr #<tag> filter)
+MATCH (e:Event)-[:TAGGED_WITH]->(t:Tag {type: $tagType})
+WHERE t.value IN $tagValues
+RETURN e
+ORDER BY e.created_at DESC
+LIMIT $limit
+```
+
+### Social Graph Pattern
+
+```cypher
+// Process contact list with diff-based updates
+// Mark old as superseded
+OPTIONAL MATCH (old:ProcessedSocialEvent {event_id: $old_event_id})
+SET old.superseded_by = $new_event_id
+
+// Create tracking node
+CREATE (new:ProcessedSocialEvent {
+  event_id: $new_event_id,
+  event_kind: 3,
+  pubkey: $author_pubkey,
+  created_at: $created_at,
+  processed_at: timestamp()
+})
+
+// Update relationships
+MERGE (author:NostrUser {pubkey: $author_pubkey})
+WITH author
+UNWIND $added_follows AS followed_pubkey
+MERGE (followed:NostrUser {pubkey: followed_pubkey})
+MERGE (author)-[:FOLLOWS]->(followed)
+```
+
+## Official Resources
+
+- Neo4j Cypher Manual: https://neo4j.com/docs/cypher-manual/current/
+- Cypher Cheat Sheet: https://neo4j.com/docs/cypher-cheat-sheet/current/
+- Query Tuning: https://neo4j.com/docs/cypher-manual/current/query-tuning/

.claude/skills/cypher/references/common-mistakes.md

@@ -0,0 +1,381 @@
+# Common Cypher Mistakes and How to Avoid Them
+
+## Clause Ordering Errors
+
+### MATCH After CREATE Without WITH
+
+**Error**: `Invalid input 'MATCH': expected ... WITH`
+
+```cypher
+// WRONG
+CREATE (e:Event {id: $id})
+MATCH (ref:Event {id: $refId})  // ERROR!
+CREATE (e)-[:REFERENCES]->(ref)
+
+// CORRECT - Use WITH to transition
+CREATE (e:Event {id: $id})
+WITH e
+MATCH (ref:Event {id: $refId})
+CREATE (e)-[:REFERENCES]->(ref)
+```
+
+**Rule**: After CREATE, you must use WITH before MATCH.
+
+### WHERE After WITH Without Carrying Variables
+
+**Error**: `Variable 'x' not defined`
+
+```cypher
+// WRONG - 'a' is lost
+MATCH (a:Author), (e:Event)
+WITH e
+WHERE a.pubkey = $pubkey  // ERROR: 'a' not in scope
+
+// CORRECT - Include all needed variables
+MATCH (a:Author), (e:Event)
+WITH a, e
+WHERE a.pubkey = $pubkey
+```
+
+**Rule**: WITH resets the scope. Include all variables you need.
+
+### ORDER BY Without Aliased Return
+
+**Error**: `Invalid input 'ORDER': expected ... AS`
+
+```cypher
+// WRONG in some contexts
+RETURN n.name
+ORDER BY n.name
+
+// SAFER - Use alias
+RETURN n.name AS name
+ORDER BY name
+```
+
+## MERGE Mistakes
+
+### MERGE on Complex Pattern Creates Duplicates
+
+```cypher
+// DANGEROUS - May create duplicate nodes
+MERGE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})
+
+// CORRECT - MERGE nodes separately first
+MERGE (a:Person {name: 'Alice'})
+MERGE (b:Person {name: 'Bob'})
+MERGE (a)-[:KNOWS]->(b)
+```
+
+**Rule**: MERGE simple patterns, not complex ones.
+
+### MERGE Without Unique Property
+
+```cypher
+// DANGEROUS - Will keep creating nodes
+MERGE (p:Person)  // No unique identifier!
+SET p.name = 'Alice'
+
+// CORRECT - Provide unique key
+MERGE (p:Person {email: $email})
+SET p.name = 'Alice'
+```
+
+**Rule**: MERGE must have properties that uniquely identify the node.
+
+### Missing ON CREATE/ON MATCH
+
+```cypher
+// LOSES context of whether new or existing
+MERGE (p:Person {id: $id})
+SET p.updated_at = timestamp()  // Always runs
+
+// BETTER - Handle each case
+MERGE (p:Person {id: $id})
+ON CREATE SET p.created_at = timestamp()
+ON MATCH SET p.updated_at = timestamp()
+```
+
+## NULL Handling Errors
+
+### Comparing with NULL
+
+```cypher
+// WRONG - NULL = NULL is NULL, not true
+WHERE n.email = null  // Never matches!
+
+// CORRECT
+WHERE n.email IS NULL
+WHERE n.email IS NOT NULL
+```
+
+### NULL in Aggregations
+
+```cypher
+// count(NULL) returns 0, collect(NULL) includes NULL
+MATCH (n:Person)
+OPTIONAL MATCH (n)-[:BOUGHT]->(p:Product)
+RETURN n.name, count(p)  // count ignores NULL
+```
+
+### NULL Propagation in Expressions
+
+```cypher
+// Any operation with NULL returns NULL
+WHERE n.age + 1 > 21  // If n.age is NULL, whole expression is NULL (falsy)
+
+// Handle with coalesce
+WHERE coalesce(n.age, 0) + 1 > 21
+```
+
+## List and IN Clause Errors
+
+### Empty List in IN
+
+```cypher
+// An empty list never matches
+WHERE n.kind IN []  // Always false
+
+// Check for empty list in application code before query
+// Or use CASE:
+WHERE CASE WHEN size($kinds) > 0 THEN n.kind IN $kinds ELSE true END
+```
+
+### IN with NULL Values
+
+```cypher
+// NULL in the list causes issues
+WHERE n.id IN [1, NULL, 3]  // NULL is never equal to anything
+
+// Filter NULLs in application code
+```
+
+## Relationship Pattern Errors
+
+### Forgetting Direction
+
+```cypher
+// WRONG - Creates both directions
+MATCH (a)-[:FOLLOWS]-(b)  // Undirected!
+
+// CORRECT - Specify direction
+MATCH (a)-[:FOLLOWS]->(b)  // a follows b
+MATCH (a)<-[:FOLLOWS]-(b)  // b follows a
+```
+
+### Variable-Length Without Bounds
+
+```cypher
+// DANGEROUS - Potentially explosive
+MATCH (a)-[*]->(b)  // Any length path!
+
+// SAFE - Set bounds
+MATCH (a)-[*1..3]->(b)  // 1 to 3 hops max
+```
+
+### Creating Duplicate Relationships
+
+```cypher
+// May create duplicates
+CREATE (a)-[:KNOWS]->(b)
+
+// Idempotent
+MERGE (a)-[:KNOWS]->(b)
+```
+
+## Performance Mistakes
+
+### Cartesian Products
+
+```cypher
+// WRONG - Cartesian product
+MATCH (a:Person), (b:Product)
+WHERE a.id = $personId AND b.id = $productId
+CREATE (a)-[:BOUGHT]->(b)
+
+// CORRECT - Single pattern or sequential
+MATCH (a:Person {id: $personId})
+MATCH (b:Product {id: $productId})
+CREATE (a)-[:BOUGHT]->(b)
+```
+
+### Late Filtering
+
+```cypher
+// SLOW - Filters after collecting everything
+MATCH (e:Event)
+WITH e
+WHERE e.kind = 1  // Should be in MATCH or right after
+
+// FAST - Filter early
+MATCH (e:Event)
+WHERE e.kind = 1
+```
+
+### Missing LIMIT with ORDER BY
+
+```cypher
+// SLOW - Sorts all results
+MATCH (e:Event)
+RETURN e
+ORDER BY e.created_at DESC
+
+// FAST - Limits result set
+MATCH (e:Event)
+RETURN e
+ORDER BY e.created_at DESC
+LIMIT 100
+```
+
+### Unparameterized Queries
+
+```cypher
+// WRONG - No query plan caching, injection risk
+MATCH (e:Event {id: '" + eventId + "'})
+
+// CORRECT - Use parameters
+MATCH (e:Event {id: $eventId})
+```
+
+## String Comparison Errors
+
+### Case Sensitivity
+
+```cypher
+// Cypher strings are case-sensitive
+WHERE n.name = 'alice'  // Won't match 'Alice'
+
+// Use toLower/toUpper for case-insensitive
+WHERE toLower(n.name) = toLower($name)
+
+// Or use regex with (?i)
+WHERE n.name =~ '(?i)alice'
+```
+
+### LIKE vs CONTAINS
+
+```cypher
+// There's no LIKE in Cypher
+WHERE n.name LIKE '%alice%'  // ERROR!
+
+// Use CONTAINS, STARTS WITH, ENDS WITH
+WHERE n.name CONTAINS 'alice'
+WHERE n.name STARTS WITH 'ali'
+WHERE n.name ENDS WITH 'ice'
+
+// Or regex for complex patterns
+WHERE n.name =~ '.*ali.*ce.*'
+```
+
+## Index Mistakes
+
+### Constraint vs Index
+
+```cypher
+// Constraint (also creates index, enforces uniqueness)
+CREATE CONSTRAINT foo IF NOT EXISTS FOR (n:Node) REQUIRE n.id IS UNIQUE
+
+// Index only (no uniqueness enforcement)
+CREATE INDEX bar IF NOT EXISTS FOR (n:Node) ON (n.id)
+```
+
+### Index Not Used
+
+```cypher
+// Index on n.id won't help here
+WHERE toLower(n.id) = $id  // Function applied to indexed property!
+
+// Store lowercase if needed, or create computed property
+```
+
+### Wrong Composite Index Order
+
+```cypher
+// Index on (kind, created_at) won't help query by created_at alone
+MATCH (e:Event) WHERE e.created_at > $since  // Index not used
+
+// Either create single-property index or query by kind too
+CREATE INDEX event_created_at FOR (e:Event) ON (e.created_at)
+```
+
+## Transaction Errors
+
+### Read After Write in Same Transaction
+
+```cypher
+// In Neo4j, reads in a transaction see the writes
+// But be careful with external processes
+CREATE (n:Node {id: 'new'})
+WITH n
+MATCH (m:Node {id: 'new'})  // Will find 'n'
+```
+
+### Locks and Deadlocks
+
+```cypher
+// MERGE takes locks; avoid complex patterns that might deadlock
+// Bad: two MERGEs on same labels in different order
+Session 1: MERGE (a:Person {id: 1}) MERGE (b:Person {id: 2})
+Session 2: MERGE (b:Person {id: 2}) MERGE (a:Person {id: 1})  // Potential deadlock
+
+// Good: consistent ordering
+Session 1: MERGE (a:Person {id: 1}) MERGE (b:Person {id: 2})
+Session 2: MERGE (a:Person {id: 1}) MERGE (b:Person {id: 2})
+```
+
+## Type Coercion Issues
+
+### Integer vs String
+
+```cypher
+// Types must match
+WHERE n.id = 123    // Won't match if n.id is "123"
+WHERE n.id = '123'  // Won't match if n.id is 123
+
+// Use appropriate parameter types from Go
+params["id"] = int64(123)   // For integer
+params["id"] = "123"        // For string
+```
+
+### Boolean Handling
+
+```cypher
+// Neo4j booleans vs strings
+WHERE n.active = true     // Boolean
+WHERE n.active = 'true'   // String - different!
+```
+
+## Delete Errors
+
+### Delete Node With Relationships
+
+```cypher
+// ERROR - Node still has relationships
+MATCH (n:Person {id: $id})
+DELETE n
+
+// CORRECT - Delete relationships first
+MATCH (n:Person {id: $id})
+DETACH DELETE n
+```
+
+### Optional Match and Delete
+
+```cypher
+// WRONG - DELETE NULL causes no error but also doesn't help
+OPTIONAL MATCH (n:Node {id: $id})
+DELETE n  // If n is NULL, nothing happens silently
+
+// Better - Check existence first or handle in application
+MATCH (n:Node {id: $id})
+DELETE n
+```
+
+## Debugging Tips
+
+1. **Use EXPLAIN** to see query plan without executing
+2. **Use PROFILE** to see actual execution metrics
+3. **Break complex queries** into smaller parts to isolate issues
+4. **Check parameter types** - mismatched types are a common issue
+5. **Verify indexes exist** with `SHOW INDEXES`
+6. **Check constraints** with `SHOW CONSTRAINTS`

.claude/skills/cypher/references/common-patterns.md

@@ -0,0 +1,397 @@
+# Common Cypher Patterns for ORLY Nostr Relay
+
+This reference contains project-specific Cypher patterns used in the ORLY Nostr relay's Neo4j backend.
+
+## Schema Overview
+
+### Node Types
+
+| Label | Purpose | Key Properties |
+|-------|---------|----------------|
+| `Event` | Nostr events (NIP-01) | `id`, `kind`, `pubkey`, `created_at`, `content`, `sig`, `tags`, `serial` |
+| `Author` | Event authors (for NIP-01 queries) | `pubkey` |
+| `Tag` | Generic tags | `type`, `value` |
+| `NostrUser` | Social graph users (WoT) | `pubkey`, `name`, `about`, `picture`, `nip05` |
+| `ProcessedSocialEvent` | Social event tracking | `event_id`, `event_kind`, `pubkey`, `superseded_by` |
+| `Marker` | Internal state markers | `key`, `value` |
+
+### Relationship Types
+
+| Type | From | To | Purpose |
+|------|------|-----|---------|
+| `AUTHORED_BY` | Event | Author | Links event to author |
+| `TAGGED_WITH` | Event | Tag | Links event to tags |
+| `REFERENCES` | Event | Event | e-tag references |
+| `MENTIONS` | Event | Author | p-tag mentions |
+| `FOLLOWS` | NostrUser | NostrUser | Contact list (kind 3) |
+| `MUTES` | NostrUser | NostrUser | Mute list (kind 10000) |
+| `REPORTS` | NostrUser | NostrUser | Reports (kind 1984) |
+
+## Event Storage Patterns
+
+### Create Event with Full Relationships
+
+This pattern creates an event and all related nodes/relationships atomically:
+
+```cypher
+// 1. Create or get author
+MERGE (a:Author {pubkey: $pubkey})
+
+// 2. Create event node
+CREATE (e:Event {
+  id: $eventId,
+  serial: $serial,
+  kind: $kind,
+  created_at: $createdAt,
+  content: $content,
+  sig: $sig,
+  pubkey: $pubkey,
+  tags: $tagsJson  // JSON string for full tag data
+})
+
+// 3. Link to author
+CREATE (e)-[:AUTHORED_BY]->(a)
+
+// 4. Process e-tags (event references)
+WITH e, a
+OPTIONAL MATCH (ref0:Event {id: $eTag_0})
+FOREACH (_ IN CASE WHEN ref0 IS NOT NULL THEN [1] ELSE [] END |
+  CREATE (e)-[:REFERENCES]->(ref0)
+)
+
+// 5. Process p-tags (mentions)
+WITH e, a
+MERGE (mentioned0:Author {pubkey: $pTag_0})
+CREATE (e)-[:MENTIONS]->(mentioned0)
+
+// 6. Process other tags
+WITH e, a
+MERGE (tag0:Tag {type: $tagType_0, value: $tagValue_0})
+CREATE (e)-[:TAGGED_WITH]->(tag0)
+
+RETURN e.id AS id
+```
+
+### Check Event Existence
+
+```cypher
+MATCH (e:Event {id: $id})
+RETURN e.id AS id
+LIMIT 1
+```
+
+### Get Next Serial Number
+
+```cypher
+MERGE (m:Marker {key: 'serial'})
+ON CREATE SET m.value = 1
+ON MATCH SET m.value = m.value + 1
+RETURN m.value AS serial
+```
+
+## Query Patterns
+
+### Basic Filter Query (NIP-01)
+
+```cypher
+MATCH (e:Event)
+WHERE e.kind IN $kinds
+  AND e.pubkey IN $authors
+  AND e.created_at >= $since
+  AND e.created_at <= $until
+RETURN e.id AS id,
+       e.kind AS kind,
+       e.created_at AS created_at,
+       e.content AS content,
+       e.sig AS sig,
+       e.pubkey AS pubkey,
+       e.tags AS tags,
+       e.serial AS serial
+ORDER BY e.created_at DESC
+LIMIT $limit
+```
+
+### Query by Event ID (with prefix support)
+
+```cypher
+// Exact match
+MATCH (e:Event {id: $id})
+RETURN e
+
+// Prefix match
+MATCH (e:Event)
+WHERE e.id STARTS WITH $idPrefix
+RETURN e
+```
+
+### Query by Tag (#<tag> filter)
+
+```cypher
+MATCH (e:Event)
+OPTIONAL MATCH (e)-[:TAGGED_WITH]->(t:Tag)
+WHERE t.type = $tagType AND t.value IN $tagValues
+RETURN DISTINCT e
+ORDER BY e.created_at DESC
+LIMIT $limit
+```
+
+### Count Events
+
+```cypher
+MATCH (e:Event)
+WHERE e.kind IN $kinds
+RETURN count(e) AS count
+```
+
+### Query Delete Events Targeting an Event
+
+```cypher
+MATCH (target:Event {id: $targetId})
+MATCH (e:Event {kind: 5})-[:REFERENCES]->(target)
+RETURN e
+ORDER BY e.created_at DESC
+```
+
+### Replaceable Event Check (kinds 0, 3, 10000-19999)
+
+```cypher
+MATCH (e:Event {kind: $kind, pubkey: $pubkey})
+WHERE e.created_at < $newCreatedAt
+RETURN e.serial AS serial
+ORDER BY e.created_at DESC
+```
+
+### Parameterized Replaceable Event Check (kinds 30000-39999)
+
+```cypher
+MATCH (e:Event {kind: $kind, pubkey: $pubkey})-[:TAGGED_WITH]->(t:Tag {type: 'd', value: $dValue})
+WHERE e.created_at < $newCreatedAt
+RETURN e.serial AS serial
+ORDER BY e.created_at DESC
+```
+
+## Social Graph Patterns
+
+### Update Profile (Kind 0)
+
+```cypher
+MERGE (user:NostrUser {pubkey: $pubkey})
+ON CREATE SET
+  user.created_at = timestamp(),
+  user.first_seen_event = $event_id
+ON MATCH SET
+  user.last_profile_update = $created_at
+SET
+  user.name = $name,
+  user.about = $about,
+  user.picture = $picture,
+  user.nip05 = $nip05,
+  user.lud16 = $lud16,
+  user.display_name = $display_name
+```
+
+### Contact List Update (Kind 3) - Diff-Based
+
+```cypher
+// Mark old event as superseded
+OPTIONAL MATCH (old:ProcessedSocialEvent {event_id: $old_event_id})
+SET old.superseded_by = $new_event_id
+
+// Create new event tracking
+CREATE (new:ProcessedSocialEvent {
+  event_id: $new_event_id,
+  event_kind: 3,
+  pubkey: $author_pubkey,
+  created_at: $created_at,
+  processed_at: timestamp(),
+  relationship_count: $total_follows,
+  superseded_by: null
+})
+
+// Get or create author
+MERGE (author:NostrUser {pubkey: $author_pubkey})
+
+// Update unchanged relationships to new event
+WITH author
+OPTIONAL MATCH (author)-[unchanged:FOLLOWS]->(followed:NostrUser)
+WHERE unchanged.created_by_event = $old_event_id
+  AND NOT followed.pubkey IN $removed_follows
+SET unchanged.created_by_event = $new_event_id,
+    unchanged.created_at = $created_at
+
+// Remove old relationships for removed follows
+WITH author
+OPTIONAL MATCH (author)-[old_follows:FOLLOWS]->(followed:NostrUser)
+WHERE old_follows.created_by_event = $old_event_id
+  AND followed.pubkey IN $removed_follows
+DELETE old_follows
+
+// Create new relationships for added follows
+WITH author
+UNWIND $added_follows AS followed_pubkey
+MERGE (followed:NostrUser {pubkey: followed_pubkey})
+MERGE (author)-[new_follows:FOLLOWS]->(followed)
+ON CREATE SET
+  new_follows.created_by_event = $new_event_id,
+  new_follows.created_at = $created_at,
+  new_follows.relay_received_at = timestamp()
+ON MATCH SET
+  new_follows.created_by_event = $new_event_id,
+  new_follows.created_at = $created_at
+```
+
+### Create Report (Kind 1984)
+
+```cypher
+// Create tracking node
+CREATE (evt:ProcessedSocialEvent {
+  event_id: $event_id,
+  event_kind: 1984,
+  pubkey: $reporter_pubkey,
+  created_at: $created_at,
+  processed_at: timestamp(),
+  relationship_count: 1,
+  superseded_by: null
+})
+
+// Create users and relationship
+MERGE (reporter:NostrUser {pubkey: $reporter_pubkey})
+MERGE (reported:NostrUser {pubkey: $reported_pubkey})
+CREATE (reporter)-[:REPORTS {
+  created_by_event: $event_id,
+  created_at: $created_at,
+  relay_received_at: timestamp(),
+  report_type: $report_type
+}]->(reported)
+```
+
+### Get Latest Social Event for Pubkey
+
+```cypher
+MATCH (evt:ProcessedSocialEvent {pubkey: $pubkey, event_kind: $kind})
+WHERE evt.superseded_by IS NULL
+RETURN evt.event_id AS event_id,
+       evt.created_at AS created_at,
+       evt.relationship_count AS relationship_count
+ORDER BY evt.created_at DESC
+LIMIT 1
+```
+
+### Get Follows for Event
+
+```cypher
+MATCH (author:NostrUser)-[f:FOLLOWS]->(followed:NostrUser)
+WHERE f.created_by_event = $event_id
+RETURN collect(followed.pubkey) AS pubkeys
+```
+
+## WoT Query Patterns
+
+### Find Mutual Follows
+
+```cypher
+MATCH (a:NostrUser {pubkey: $pubkeyA})-[:FOLLOWS]->(b:NostrUser)
+WHERE (b)-[:FOLLOWS]->(a)
+RETURN b.pubkey AS mutual_friend
+```
+
+### Find Followers
+
+```cypher
+MATCH (follower:NostrUser)-[:FOLLOWS]->(user:NostrUser {pubkey: $pubkey})
+RETURN follower.pubkey, follower.name
+```
+
+### Find Following
+
+```cypher
+MATCH (user:NostrUser {pubkey: $pubkey})-[:FOLLOWS]->(following:NostrUser)
+RETURN following.pubkey, following.name
+```
+
+### Hop Distance (Trust Path)
+
+```cypher
+MATCH (start:NostrUser {pubkey: $startPubkey})
+MATCH (end:NostrUser {pubkey: $endPubkey})
+MATCH path = shortestPath((start)-[:FOLLOWS*..6]->(end))
+RETURN length(path) AS hops, [n IN nodes(path) | n.pubkey] AS path
+```
+
+### Second-Degree Connections
+
+```cypher
+MATCH (me:NostrUser {pubkey: $myPubkey})-[:FOLLOWS]->(:NostrUser)-[:FOLLOWS]->(suggested:NostrUser)
+WHERE NOT (me)-[:FOLLOWS]->(suggested)
+  AND suggested.pubkey <> $myPubkey
+RETURN suggested.pubkey, count(*) AS commonFollows
+ORDER BY commonFollows DESC
+LIMIT 20
+```
+
+## Schema Management Patterns
+
+### Create Constraint
+
+```cypher
+CREATE CONSTRAINT event_id_unique IF NOT EXISTS
+FOR (e:Event) REQUIRE e.id IS UNIQUE
+```
+
+### Create Index
+
+```cypher
+CREATE INDEX event_kind IF NOT EXISTS
+FOR (e:Event) ON (e.kind)
+```
+
+### Create Composite Index
+
+```cypher
+CREATE INDEX event_kind_created_at IF NOT EXISTS
+FOR (e:Event) ON (e.kind, e.created_at)
+```
+
+### Drop All Data (Testing Only)
+
+```cypher
+MATCH (n) DETACH DELETE n
+```
+
+## Performance Patterns
+
+### Use EXPLAIN/PROFILE
+
+```cypher
+// See query plan without running
+EXPLAIN MATCH (e:Event) WHERE e.kind = 1 RETURN e
+
+// Run and see actual metrics
+PROFILE MATCH (e:Event) WHERE e.kind = 1 RETURN e
+```
+
+### Batch Import with UNWIND
+
+```cypher
+UNWIND $events AS evt
+CREATE (e:Event {
+  id: evt.id,
+  kind: evt.kind,
+  pubkey: evt.pubkey,
+  created_at: evt.created_at,
+  content: evt.content,
+  sig: evt.sig,
+  tags: evt.tags
+})
+```
+
+### Efficient Pagination
+
+```cypher
+// Use indexed ORDER BY with WHERE for cursor-based pagination
+MATCH (e:Event)
+WHERE e.kind = 1 AND e.created_at < $cursor
+RETURN e
+ORDER BY e.created_at DESC
+LIMIT 20
+```

.claude/skills/cypher/references/syntax-reference.md

@@ -0,0 +1,540 @@
+# Cypher Syntax Reference
+
+Complete syntax reference for Neo4j Cypher query language.
+
+## Clause Reference
+
+### Reading Clauses
+
+#### MATCH
+
+Finds patterns in the graph.
+
+```cypher
+// Basic node match
+MATCH (n:Label)
+
+// Match with properties
+MATCH (n:Label {key: value})
+
+// Match relationships
+MATCH (a)-[r:RELATES_TO]->(b)
+
+// Match path
+MATCH path = (a)-[*1..3]->(b)
+```
+
+#### OPTIONAL MATCH
+
+Like MATCH but returns NULL for non-matches (LEFT OUTER JOIN).
+
+```cypher
+MATCH (a:Person)
+OPTIONAL MATCH (a)-[:KNOWS]->(b:Person)
+RETURN a.name, b.name  // b.name may be NULL
+```
+
+#### WHERE
+
+Filters results.
+
+```cypher
+// Comparison operators
+WHERE n.age > 21
+WHERE n.age >= 21
+WHERE n.age < 65
+WHERE n.age <= 65
+WHERE n.name = 'Alice'
+WHERE n.name <> 'Bob'
+
+// Boolean operators
+WHERE n.age > 21 AND n.active = true
+WHERE n.age < 18 OR n.age > 65
+WHERE NOT n.deleted
+
+// NULL checks
+WHERE n.email IS NULL
+WHERE n.email IS NOT NULL
+
+// Pattern predicates
+WHERE (n)-[:KNOWS]->(:Person)
+WHERE NOT (n)-[:BLOCKED]->()
+WHERE exists((n)-[:FOLLOWS]->())
+
+// String predicates
+WHERE n.name STARTS WITH 'A'
+WHERE n.name ENDS WITH 'son'
+WHERE n.name CONTAINS 'li'
+WHERE n.name =~ '(?i)alice.*'  // Case-insensitive regex
+
+// List predicates
+WHERE n.status IN ['active', 'pending']
+WHERE any(x IN n.tags WHERE x = 'important')
+WHERE all(x IN n.scores WHERE x > 50)
+WHERE none(x IN n.errors WHERE x IS NOT NULL)
+WHERE single(x IN n.items WHERE x.primary = true)
+```
+
+### Writing Clauses
+
+#### CREATE
+
+Creates nodes and relationships.
+
+```cypher
+// Create node
+CREATE (n:Label {key: value})
+
+// Create multiple nodes
+CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
+
+// Create relationship
+CREATE (a)-[r:KNOWS {since: 2020}]->(b)
+
+// Create path
+CREATE p = (a)-[:KNOWS]->(b)-[:KNOWS]->(c)
+```
+
+#### MERGE
+
+Find or create pattern. **Critical for idempotency**.
+
+```cypher
+// MERGE node
+MERGE (n:Label {key: $uniqueKey})
+
+// MERGE with ON CREATE / ON MATCH
+MERGE (n:Person {email: $email})
+ON CREATE SET n.created = timestamp(), n.name = $name
+ON MATCH SET n.accessed = timestamp()
+
+// MERGE relationship (both nodes must exist or be in scope)
+MERGE (a)-[r:KNOWS]->(b)
+ON CREATE SET r.since = date()
+```
+
+**MERGE Gotcha**: MERGE on a pattern locks the entire pattern. For relationships, MERGE each node first:
+
+```cypher
+// CORRECT
+MERGE (a:Person {id: $id1})
+MERGE (b:Person {id: $id2})
+MERGE (a)-[:KNOWS]->(b)
+
+// RISKY - may create duplicate nodes
+MERGE (a:Person {id: $id1})-[:KNOWS]->(b:Person {id: $id2})
+```
+
+#### SET
+
+Updates properties.
+
+```cypher
+// Set single property
+SET n.name = 'Alice'
+
+// Set multiple properties
+SET n.name = 'Alice', n.age = 30
+
+// Set from map (replaces all properties)
+SET n = {name: 'Alice', age: 30}
+
+// Set from map (adds/updates, keeps existing)
+SET n += {name: 'Alice'}
+
+// Set label
+SET n:NewLabel
+
+// Remove property
+SET n.obsolete = null
+```
+
+#### DELETE / DETACH DELETE
+
+Removes nodes and relationships.
+
+```cypher
+// Delete relationship
+MATCH (a)-[r:KNOWS]->(b)
+DELETE r
+
+// Delete node (must have no relationships)
+MATCH (n:Orphan)
+DELETE n
+
+// Delete node and all relationships
+MATCH (n:Person {name: 'Bob'})
+DETACH DELETE n
+```
+
+#### REMOVE
+
+Removes properties and labels.
+
+```cypher
+// Remove property
+REMOVE n.temporary
+
+// Remove label
+REMOVE n:OldLabel
+```
+
+### Projection Clauses
+
+#### RETURN
+
+Specifies output.
+
+```cypher
+// Return nodes
+RETURN n
+
+// Return properties
+RETURN n.name, n.age
+
+// Return with alias
+RETURN n.name AS name, n.age AS age
+
+// Return all
+RETURN *
+
+// Return distinct
+RETURN DISTINCT n.category
+
+// Return expression
+RETURN n.price * n.quantity AS total
+```
+
+#### WITH
+
+Passes results between query parts. **Critical for multi-part queries**.
+
+```cypher
+// Filter and pass
+MATCH (n:Person)
+WITH n WHERE n.age > 21
+RETURN n
+
+// Aggregate and continue
+MATCH (n:Person)-[:BOUGHT]->(p:Product)
+WITH n, count(p) AS purchases
+WHERE purchases > 5
+RETURN n.name, purchases
+
+// Order and limit mid-query
+MATCH (n:Person)
+WITH n ORDER BY n.age DESC LIMIT 10
+MATCH (n)-[:LIVES_IN]->(c:City)
+RETURN n.name, c.name
+```
+
+**WITH resets scope**: Variables not listed in WITH are no longer available.
+
+#### ORDER BY
+
+Sorts results.
+
+```cypher
+ORDER BY n.name                    // Ascending (default)
+ORDER BY n.name ASC               // Explicit ascending
+ORDER BY n.name DESC              // Descending
+ORDER BY n.lastName, n.firstName  // Multiple fields
+ORDER BY n.priority DESC, n.name  // Mixed
+```
+
+#### SKIP and LIMIT
+
+Pagination.
+
+```cypher
+// Skip first 10
+SKIP 10
+
+// Return only 20
+LIMIT 20
+
+// Pagination
+ORDER BY n.created_at DESC
+SKIP $offset LIMIT $pageSize
+```
+
+### Sub-queries
+
+#### CALL (Subquery)
+
+Execute subquery for each row.
+
+```cypher
+MATCH (p:Person)
+CALL {
+  WITH p
+  MATCH (p)-[:BOUGHT]->(prod:Product)
+  RETURN count(prod) AS purchaseCount
+}
+RETURN p.name, purchaseCount
+```
+
+#### UNION
+
+Combine results from multiple queries.
+
+```cypher
+MATCH (n:Person) RETURN n.name AS name
+UNION
+MATCH (n:Company) RETURN n.name AS name
+
+// UNION ALL keeps duplicates
+MATCH (n:Person) RETURN n.name AS name
+UNION ALL
+MATCH (n:Company) RETURN n.name AS name
+```
+
+### Control Flow
+
+#### FOREACH
+
+Iterate over list, execute updates.
+
+```cypher
+// Set property on path nodes
+MATCH path = (a)-[*]->(b)
+FOREACH (n IN nodes(path) | SET n.visited = true)
+
+// Conditional operation (common pattern)
+OPTIONAL MATCH (target:Node {id: $id})
+FOREACH (_ IN CASE WHEN target IS NOT NULL THEN [1] ELSE [] END |
+  CREATE (source)-[:LINKS_TO]->(target)
+)
+```
+
+#### CASE
+
+Conditional expressions.
+
+```cypher
+// Simple CASE
+RETURN CASE n.status
+  WHEN 'active' THEN 'A'
+  WHEN 'pending' THEN 'P'
+  ELSE 'X'
+END AS code
+
+// Generic CASE
+RETURN CASE
+  WHEN n.age < 18 THEN 'minor'
+  WHEN n.age < 65 THEN 'adult'
+  ELSE 'senior'
+END AS category
+```
+
+## Operators
+
+### Comparison
+
+| Operator | Description |
+|----------|-------------|
+| `=` | Equal |
+| `<>` | Not equal |
+| `<` | Less than |
+| `>` | Greater than |
+| `<=` | Less than or equal |
+| `>=` | Greater than or equal |
+| `IS NULL` | Is null |
+| `IS NOT NULL` | Is not null |
+
+### Boolean
+
+| Operator | Description |
+|----------|-------------|
+| `AND` | Logical AND |
+| `OR` | Logical OR |
+| `NOT` | Logical NOT |
+| `XOR` | Exclusive OR |
+
+### String
+
+| Operator | Description |
+|----------|-------------|
+| `STARTS WITH` | Prefix match |
+| `ENDS WITH` | Suffix match |
+| `CONTAINS` | Substring match |
+| `=~` | Regex match |
+
+### List
+
+| Operator | Description |
+|----------|-------------|
+| `IN` | List membership |
+| `+` | List concatenation |
+
+### Mathematical
+
+| Operator | Description |
+|----------|-------------|
+| `+` | Addition |
+| `-` | Subtraction |
+| `*` | Multiplication |
+| `/` | Division |
+| `%` | Modulo |
+| `^` | Exponentiation |
+
+## Functions
+
+### Aggregation
+
+```cypher
+count(*)              // Count rows
+count(n)              // Count non-null
+count(DISTINCT n)     // Count unique
+sum(n.value)          // Sum
+avg(n.value)          // Average
+min(n.value)          // Minimum
+max(n.value)          // Maximum
+collect(n)            // Collect to list
+collect(DISTINCT n)   // Collect unique
+stDev(n.value)        // Standard deviation
+percentileCont(n.value, 0.5)  // Median
+```
+
+### Scalar
+
+```cypher
+// Type functions
+id(n)                 // Internal node ID (deprecated, use elementId)
+elementId(n)          // Element ID string
+labels(n)             // Node labels
+type(r)               // Relationship type
+properties(n)         // Property map
+
+// Math
+abs(x)
+ceil(x)
+floor(x)
+round(x)
+sign(x)
+sqrt(x)
+rand()                // Random 0-1
+
+// String
+size(str)             // String length
+toLower(str)
+toUpper(str)
+trim(str)
+ltrim(str)
+rtrim(str)
+replace(str, from, to)
+substring(str, start, len)
+left(str, len)
+right(str, len)
+split(str, delimiter)
+reverse(str)
+toString(val)
+
+// Null handling
+coalesce(val1, val2, ...)  // First non-null
+nullIf(val1, val2)         // NULL if equal
+
+// Type conversion
+toInteger(val)
+toFloat(val)
+toBoolean(val)
+toString(val)
+```
+
+### List Functions
+
+```cypher
+size(list)            // List length
+head(list)            // First element
+tail(list)            // All but first
+last(list)            // Last element
+range(start, end)     // Create range [start..end]
+range(start, end, step)
+reverse(list)
+keys(map)             // Map keys as list
+values(map)           // Map values as list
+
+// List predicates
+any(x IN list WHERE predicate)
+all(x IN list WHERE predicate)
+none(x IN list WHERE predicate)
+single(x IN list WHERE predicate)
+
+// List manipulation
+[x IN list WHERE predicate]           // Filter
+[x IN list | expression]              // Map
+[x IN list WHERE pred | expr]         // Filter and map
+reduce(s = initial, x IN list | s + x) // Reduce
+```
+
+### Path Functions
+
+```cypher
+nodes(path)           // Nodes in path
+relationships(path)   // Relationships in path
+length(path)          // Number of relationships
+shortestPath((a)-[*]-(b))
+allShortestPaths((a)-[*]-(b))
+```
+
+### Temporal Functions
+
+```cypher
+timestamp()           // Current Unix timestamp (ms)
+datetime()            // Current datetime
+date()                // Current date
+time()                // Current time
+duration({days: 1, hours: 12})
+
+// Components
+datetime().year
+datetime().month
+datetime().day
+datetime().hour
+
+// Parsing
+date('2024-01-15')
+datetime('2024-01-15T10:30:00Z')
+```
+
+### Spatial Functions
+
+```cypher
+point({x: 1, y: 2})
+point({latitude: 37.5, longitude: -122.4})
+distance(point1, point2)
+```
+
+## Comments
+
+```cypher
+// Single line comment
+
+/* Multi-line
+   comment */
+```
+
+## Transaction Control
+
+```cypher
+// In procedures/transactions
+:begin
+:commit
+:rollback
+```
+
+## Parameter Syntax
+
+```cypher
+// Parameter reference
+$paramName
+
+// In properties
+{key: $value}
+
+// In WHERE
+WHERE n.id = $id
+
+// In expressions
+RETURN $multiplier * n.value
+```

.claude/skills/distributed-systems/references/consensus-protocols.md

@@ -0,0 +1,610 @@
+# Consensus Protocols - Detailed Reference
+
+Complete specifications and implementation details for major consensus protocols.
+
+## Paxos Complete Specification
+
+### Proposal Numbers
+
+Proposal numbers must be:
+- **Unique**: No two proposers use the same number
+- **Totally ordered**: Any two can be compared
+
+**Implementation**: `(round_number, proposer_id)` where proposer_id breaks ties.
+
+### Single-Decree Paxos State
+
+**Proposer state**:
+```
+proposal_number: int
+value: any
+```
+
+**Acceptor state (persistent)**:
+```
+highest_promised: int    # Highest proposal number promised
+accepted_proposal: int   # Number of accepted proposal (0 if none)
+accepted_value: any      # Value of accepted proposal (null if none)
+```
+
+### Message Format
+
+**Prepare** (Phase 1a):
+```
+{
+  type: "PREPARE",
+  proposal_number: n
+}
+```
+
+**Promise** (Phase 1b):
+```
+{
+  type: "PROMISE",
+  proposal_number: n,
+  accepted_proposal: m,    # null if nothing accepted
+  accepted_value: v        # null if nothing accepted
+}
+```
+
+**Accept** (Phase 2a):
+```
+{
+  type: "ACCEPT",
+  proposal_number: n,
+  value: v
+}
+```
+
+**Accepted** (Phase 2b):
+```
+{
+  type: "ACCEPTED",
+  proposal_number: n,
+  value: v
+}
+```
+
+### Proposer Algorithm
+
+```
+function propose(value):
+    n = generate_proposal_number()
+
+    # Phase 1: Prepare
+    promises = []
+    for acceptor in acceptors:
+        send PREPARE(n) to acceptor
+
+    wait until |promises| > |acceptors|/2 or timeout
+
+    if timeout:
+        return FAILED
+
+    # Choose value
+    highest = max(promises, key=p.accepted_proposal)
+    if highest.accepted_value is not null:
+        value = highest.accepted_value
+
+    # Phase 2: Accept
+    accepts = []
+    for acceptor in acceptors:
+        send ACCEPT(n, value) to acceptor
+
+    wait until |accepts| > |acceptors|/2 or timeout
+
+    if timeout:
+        return FAILED
+
+    return SUCCESS(value)
+```
+
+### Acceptor Algorithm
+
+```
+on receive PREPARE(n):
+    if n > highest_promised:
+        highest_promised = n
+        persist(highest_promised)
+        reply PROMISE(n, accepted_proposal, accepted_value)
+    else:
+        # Optionally reply NACK(highest_promised)
+        ignore or reject
+
+on receive ACCEPT(n, v):
+    if n >= highest_promised:
+        highest_promised = n
+        accepted_proposal = n
+        accepted_value = v
+        persist(highest_promised, accepted_proposal, accepted_value)
+        reply ACCEPTED(n, v)
+    else:
+        ignore or reject
+```
+
+### Multi-Paxos Optimization
+
+**Stable leader**:
+```
+# Leader election (using Paxos or other method)
+leader = elect_leader()
+
+# Leader's Phase 1 for all future instances
+leader sends PREPARE(n) for instance range [i, ∞)
+
+# For each command:
+function propose_as_leader(value, instance):
+    # Skip Phase 1 if already leader
+    for acceptor in acceptors:
+        send ACCEPT(n, value, instance) to acceptor
+    wait for majority ACCEPTED
+    return SUCCESS
+```
+
+### Paxos Safety Proof Sketch
+
+**Invariant**: If a value v is chosen for instance i, no other value can be chosen.
+
+**Proof**:
+1. Value chosen → accepted by majority with proposal n
+2. Any higher proposal n' must contact majority
+3. Majorities intersect → at least one acceptor has accepted v
+4. New proposer adopts v (or higher already-accepted value)
+5. By induction, all future proposals use v
+
+## Raft Complete Specification
+
+### State
+
+**All servers (persistent)**:
+```
+currentTerm: int      # Latest term seen
+votedFor: ServerId    # Candidate voted for in current term (null if none)
+log[]: LogEntry       # Log entries
+```
+
+**All servers (volatile)**:
+```
+commitIndex: int      # Highest log index known to be committed
+lastApplied: int      # Highest log index applied to state machine
+```
+
+**Leader (volatile, reinitialized after election)**:
+```
+nextIndex[]: int      # For each server, next log index to send
+matchIndex[]: int     # For each server, highest log index replicated
+```
+
+**LogEntry**:
+```
+{
+  term: int,
+  command: any
+}
+```
+
+### RequestVote RPC
+
+**Request**:
+```
+{
+  term: int,              # Candidate's term
+  candidateId: ServerId,  # Candidate requesting vote
+  lastLogIndex: int,      # Index of candidate's last log entry
+  lastLogTerm: int        # Term of candidate's last log entry
+}
+```
+
+**Response**:
+```
+{
+  term: int,              # currentTerm, for candidate to update itself
+  voteGranted: bool       # True if candidate received vote
+}
+```
+
+**Receiver implementation**:
+```
+on receive RequestVote(term, candidateId, lastLogIndex, lastLogTerm):
+    if term < currentTerm:
+        return {term: currentTerm, voteGranted: false}
+
+    if term > currentTerm:
+        currentTerm = term
+        votedFor = null
+        convert to follower
+
+    # Check if candidate's log is at least as up-to-date as ours
+    ourLastTerm = log[len(log)-1].term if log else 0
+    ourLastIndex = len(log) - 1
+
+    logOK = (lastLogTerm > ourLastTerm) or
+            (lastLogTerm == ourLastTerm and lastLogIndex >= ourLastIndex)
+
+    if (votedFor is null or votedFor == candidateId) and logOK:
+        votedFor = candidateId
+        persist(currentTerm, votedFor)
+        reset election timer
+        return {term: currentTerm, voteGranted: true}
+
+    return {term: currentTerm, voteGranted: false}
+```
+
+### AppendEntries RPC
+
+**Request**:
+```
+{
+  term: int,              # Leader's term
+  leaderId: ServerId,     # For follower to redirect clients
+  prevLogIndex: int,      # Index of log entry preceding new ones
+  prevLogTerm: int,       # Term of prevLogIndex entry
+  entries[]: LogEntry,    # Log entries to store (empty for heartbeat)
+  leaderCommit: int       # Leader's commitIndex
+}
+```
+
+**Response**:
+```
+{
+  term: int,              # currentTerm, for leader to update itself
+  success: bool           # True if follower had matching prevLog entry
+}
+```
+
+**Receiver implementation**:
+```
+on receive AppendEntries(term, leaderId, prevLogIndex, prevLogTerm, entries, leaderCommit):
+    if term < currentTerm:
+        return {term: currentTerm, success: false}
+
+    reset election timer
+
+    if term > currentTerm:
+        currentTerm = term
+        votedFor = null
+
+    convert to follower
+
+    # Check log consistency
+    if prevLogIndex >= len(log) or
+       (prevLogIndex >= 0 and log[prevLogIndex].term != prevLogTerm):
+        return {term: currentTerm, success: false}
+
+    # Append new entries (handling conflicts)
+    for i, entry in enumerate(entries):
+        index = prevLogIndex + 1 + i
+        if index < len(log):
+            if log[index].term != entry.term:
+                # Delete conflicting entry and all following
+                log = log[:index]
+                log.append(entry)
+        else:
+            log.append(entry)
+
+    persist(currentTerm, votedFor, log)
+
+    # Update commit index
+    if leaderCommit > commitIndex:
+        commitIndex = min(leaderCommit, len(log) - 1)
+
+    return {term: currentTerm, success: true}
+```
+
+### Leader Behavior
+
+```
+on becoming leader:
+    for each server:
+        nextIndex[server] = len(log)
+        matchIndex[server] = 0
+
+    start sending heartbeats
+
+on receiving client command:
+    append entry to local log
+    persist log
+    send AppendEntries to all followers
+
+on receiving AppendEntries response from server:
+    if response.success:
+        matchIndex[server] = prevLogIndex + len(entries)
+        nextIndex[server] = matchIndex[server] + 1
+
+        # Update commit index
+        for N from commitIndex+1 to len(log)-1:
+            if log[N].term == currentTerm and
+               |{s : matchIndex[s] >= N}| > |servers|/2:
+                commitIndex = N
+    else:
+        nextIndex[server] = max(1, nextIndex[server] - 1)
+        retry AppendEntries with lower prevLogIndex
+
+on commitIndex update:
+    while lastApplied < commitIndex:
+        lastApplied++
+        apply log[lastApplied].command to state machine
+```
+
+### Election Timeout
+
+```
+on election timeout (follower or candidate):
+    currentTerm++
+    convert to candidate
+    votedFor = self
+    persist(currentTerm, votedFor)
+    reset election timer
+    votes = 1  # Vote for self
+
+    for each server except self:
+        send RequestVote(currentTerm, self, lastLogIndex, lastLogTerm)
+
+    wait for responses or timeout:
+        if received votes > |servers|/2:
+            become leader
+        if received AppendEntries from valid leader:
+            become follower
+        if timeout:
+            start new election
+```
+
+## PBFT Complete Specification
+
+### Message Types
+
+**REQUEST**:
+```
+{
+  type: "REQUEST",
+  operation: o,           # Operation to execute
+  timestamp: t,           # Client timestamp (for reply matching)
+  client: c               # Client identifier
+}
+```
+
+**PRE-PREPARE**:
+```
+{
+  type: "PRE-PREPARE",
+  view: v,                # Current view number
+  sequence: n,            # Sequence number
+  digest: d,              # Hash of request
+  request: m              # The request message
+}
+signature(primary)
+```
+
+**PREPARE**:
+```
+{
+  type: "PREPARE",
+  view: v,
+  sequence: n,
+  digest: d,
+  replica: i              # Sending replica
+}
+signature(replica_i)
+```
+
+**COMMIT**:
+```
+{
+  type: "COMMIT",
+  view: v,
+  sequence: n,
+  digest: d,
+  replica: i
+}
+signature(replica_i)
+```
+
+**REPLY**:
+```
+{
+  type: "REPLY",
+  view: v,
+  timestamp: t,
+  client: c,
+  replica: i,
+  result: r               # Execution result
+}
+signature(replica_i)
+```
+
+### Replica State
+
+```
+view: int                       # Current view
+sequence: int                   # Last assigned sequence number (primary)
+log[]: {request, prepares, commits, state}  # Log of requests
+prepared_certificates: {}       # Prepared certificates (2f+1 prepares)
+committed_certificates: {}      # Committed certificates (2f+1 commits)
+h: int                          # Low water mark
+H: int                          # High water mark (h + L)
+```
+
+### Normal Operation Protocol
+
+**Primary (replica p = v mod n)**:
+```
+on receive REQUEST(m) from client:
+    if not primary for current view:
+        forward to primary
+        return
+
+    n = assign_sequence_number()
+    d = hash(m)
+
+    broadcast PRE-PREPARE(v, n, d, m) to all replicas
+    add to log
+```
+
+**All replicas**:
+```
+on receive PRE-PREPARE(v, n, d, m) from primary:
+    if v != current_view:
+        ignore
+    if already accepted pre-prepare for (v, n) with different digest:
+        ignore
+    if not in_view_as_backup(v):
+        ignore
+    if not h < n <= H:
+        ignore  # Outside sequence window
+
+    # Valid pre-prepare
+    add to log
+    broadcast PREPARE(v, n, d, i) to all replicas
+
+on receive PREPARE(v, n, d, j) from replica j:
+    if v != current_view:
+        ignore
+
+    add to log[n].prepares
+
+    if |log[n].prepares| >= 2f and not already_prepared(v, n, d):
+        # Prepared certificate complete
+        mark as prepared
+        broadcast COMMIT(v, n, d, i) to all replicas
+
+on receive COMMIT(v, n, d, j) from replica j:
+    if v != current_view:
+        ignore
+
+    add to log[n].commits
+
+    if |log[n].commits| >= 2f + 1 and prepared(v, n, d):
+        # Committed certificate complete
+        if all entries < n are committed:
+            execute(m)
+            send REPLY(v, t, c, i, result) to client
+```
+
+### View Change Protocol
+
+**Timeout trigger**:
+```
+on request timeout (no progress):
+    view_change_timeout++
+    broadcast VIEW-CHANGE(v+1, n, C, P, i)
+
+    where:
+      n = last stable checkpoint sequence number
+      C = checkpoint certificate (2f+1 checkpoint messages)
+      P = set of prepared certificates for messages after n
+```
+
+**VIEW-CHANGE**:
+```
+{
+  type: "VIEW-CHANGE",
+  view: v,                      # New view number
+  sequence: n,                  # Checkpoint sequence
+  checkpoints: C,               # Checkpoint certificate
+  prepared: P,                  # Set of prepared certificates
+  replica: i
+}
+signature(replica_i)
+```
+
+**New primary (p' = v mod n)**:
+```
+on receive 2f VIEW-CHANGE for view v:
+    V = set of valid view-change messages
+
+    # Compute O: set of requests to re-propose
+    O = {}
+    for seq in max_checkpoint_seq(V) to max_seq(V):
+        if exists prepared certificate for seq in V:
+            O[seq] = request from certificate
+        else:
+            O[seq] = null-request  # No-op
+
+    broadcast NEW-VIEW(v, V, O)
+
+    # Re-run protocol for requests in O
+    for seq, request in O:
+        if request != null:
+            send PRE-PREPARE(v, seq, hash(request), request)
+```
+
+**NEW-VIEW**:
+```
+{
+  type: "NEW-VIEW",
+  view: v,
+  view_changes: V,              # 2f+1 view-change messages
+  pre_prepares: O               # Set of pre-prepare messages
+}
+signature(primary)
+```
+
+### Checkpointing
+
+Periodic stable checkpoints to garbage collect logs:
+
+```
+every K requests:
+    state_hash = hash(state_machine_state)
+    broadcast CHECKPOINT(n, state_hash, i)
+
+on receive 2f+1 CHECKPOINT for (n, d):
+    if all digests match:
+        create stable checkpoint
+        h = n  # Move low water mark
+        garbage_collect(entries < n)
+```
+
+## HotStuff Protocol
+
+Linear complexity BFT using threshold signatures.
+
+### Key Innovation
+
+- **Three-phase**: prepare → pre-commit → commit → decide
+- **Pipelining**: Next proposal starts before current finishes
+- **Threshold signatures**: O(n) total messages instead of O(n²)
+
+### Message Flow
+
+```
+Phase 1 (Prepare):
+  Leader: broadcast PREPARE(v, node)
+  Replicas: sign and send partial signature to leader
+  Leader: aggregate into prepare certificate QC
+
+Phase 2 (Pre-commit):
+  Leader: broadcast PRE-COMMIT(v, QC_prepare)
+  Replicas: sign and send partial signature
+  Leader: aggregate into pre-commit certificate
+
+Phase 3 (Commit):
+  Leader: broadcast COMMIT(v, QC_precommit)
+  Replicas: sign and send partial signature
+  Leader: aggregate into commit certificate
+
+Phase 4 (Decide):
+  Leader: broadcast DECIDE(v, QC_commit)
+  Replicas: execute and commit
+```
+
+### Pipelining
+
+```
+Block k:   [prepare] [pre-commit] [commit] [decide]
+Block k+1:          [prepare] [pre-commit] [commit] [decide]
+Block k+2:                   [prepare] [pre-commit] [commit] [decide]
+```
+
+Each phase of block k+1 piggybacks on messages for block k.
+
+## Protocol Comparison Matrix
+
+| Feature | Paxos | Raft | PBFT | HotStuff |
+|---------|-------|------|------|----------|
+| Fault model | Crash | Crash | Byzantine | Byzantine |
+| Fault tolerance | f with 2f+1 | f with 2f+1 | f with 3f+1 | f with 3f+1 |
+| Message complexity | O(n) | O(n) | O(n²) | O(n) |
+| Leader required | No (helps) | Yes | Yes | Yes |
+| Phases | 2 | 2 | 3 | 3 |
+| View change | Complex | Simple | Complex | Simple |

.claude/skills/distributed-systems/references/logical-clocks.md

@@ -0,0 +1,610 @@
+# Logical Clocks - Implementation Reference
+
+Detailed implementations and algorithms for causality tracking.
+
+## Lamport Clock Implementation
+
+### Data Structure
+
+```go
+type LamportClock struct {
+    counter uint64
+    mu      sync.Mutex
+}
+
+func NewLamportClock() *LamportClock {
+    return &LamportClock{counter: 0}
+}
+```
+
+### Operations
+
+```go
+// Tick increments clock for local event
+func (c *LamportClock) Tick() uint64 {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.counter++
+    return c.counter
+}
+
+// Send returns timestamp for outgoing message
+func (c *LamportClock) Send() uint64 {
+    return c.Tick()
+}
+
+// Receive updates clock based on incoming message timestamp
+func (c *LamportClock) Receive(msgTime uint64) uint64 {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+
+    if msgTime > c.counter {
+        c.counter = msgTime
+    }
+    c.counter++
+    return c.counter
+}
+
+// Time returns current clock value without incrementing
+func (c *LamportClock) Time() uint64 {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    return c.counter
+}
+```
+
+### Usage Example
+
+```go
+// Process A
+clockA := NewLamportClock()
+e1 := clockA.Tick()      // Event 1: time=1
+msgTime := clockA.Send() // Send: time=2
+
+// Process B
+clockB := NewLamportClock()
+e2 := clockB.Tick()           // Event 2: time=1
+e3 := clockB.Receive(msgTime) // Receive: time=3 (max(1,2)+1)
+```
+
+## Vector Clock Implementation
+
+### Data Structure
+
+```go
+type VectorClock struct {
+    clocks map[string]uint64  // processID -> logical time
+    self   string             // this process's ID
+    mu     sync.RWMutex
+}
+
+func NewVectorClock(processID string, allProcesses []string) *VectorClock {
+    clocks := make(map[string]uint64)
+    for _, p := range allProcesses {
+        clocks[p] = 0
+    }
+    return &VectorClock{
+        clocks: clocks,
+        self:   processID,
+    }
+}
+```
+
+### Operations
+
+```go
+// Tick increments own clock
+func (vc *VectorClock) Tick() map[string]uint64 {
+    vc.mu.Lock()
+    defer vc.mu.Unlock()
+
+    vc.clocks[vc.self]++
+    return vc.copy()
+}
+
+// Send returns copy of vector for message
+func (vc *VectorClock) Send() map[string]uint64 {
+    return vc.Tick()
+}
+
+// Receive merges incoming vector and increments
+func (vc *VectorClock) Receive(incoming map[string]uint64) map[string]uint64 {
+    vc.mu.Lock()
+    defer vc.mu.Unlock()
+
+    // Merge: take max of each component
+    for pid, time := range incoming {
+        if time > vc.clocks[pid] {
+            vc.clocks[pid] = time
+        }
+    }
+
+    // Increment own clock
+    vc.clocks[vc.self]++
+    return vc.copy()
+}
+
+// copy returns a copy of the vector
+func (vc *VectorClock) copy() map[string]uint64 {
+    result := make(map[string]uint64)
+    for k, v := range vc.clocks {
+        result[k] = v
+    }
+    return result
+}
+```
+
+### Comparison Functions
+
+```go
+// Compare returns ordering relationship between two vectors
+type Ordering int
+
+const (
+    Equal      Ordering = iota // V1 == V2
+    HappenedBefore            // V1 < V2
+    HappenedAfter             // V1 > V2
+    Concurrent                // V1 || V2
+)
+
+func Compare(v1, v2 map[string]uint64) Ordering {
+    less := false
+    greater := false
+
+    // Get all keys
+    allKeys := make(map[string]bool)
+    for k := range v1 {
+        allKeys[k] = true
+    }
+    for k := range v2 {
+        allKeys[k] = true
+    }
+
+    for k := range allKeys {
+        t1 := v1[k] // 0 if not present
+        t2 := v2[k]
+
+        if t1 < t2 {
+            less = true
+        }
+        if t1 > t2 {
+            greater = true
+        }
+    }
+
+    if !less && !greater {
+        return Equal
+    }
+    if less && !greater {
+        return HappenedBefore
+    }
+    if greater && !less {
+        return HappenedAfter
+    }
+    return Concurrent
+}
+
+// IsConcurrent checks if two events are concurrent
+func IsConcurrent(v1, v2 map[string]uint64) bool {
+    return Compare(v1, v2) == Concurrent
+}
+
+// HappenedBefore checks if v1 -> v2 (v1 causally precedes v2)
+func HappenedBefore(v1, v2 map[string]uint64) bool {
+    return Compare(v1, v2) == HappenedBefore
+}
+```
+
+## Interval Tree Clock Implementation
+
+### Data Structures
+
+```go
+// ID represents the identity tree
+type ID struct {
+    IsLeaf bool
+    Value  int   // 0 or 1 for leaves
+    Left   *ID   // nil for leaves
+    Right  *ID
+}
+
+// Stamp represents the event tree
+type Stamp struct {
+    Base  int
+    Left  *Stamp // nil for leaf stamps
+    Right *Stamp
+}
+
+// ITC combines ID and Stamp
+type ITC struct {
+    ID    *ID
+    Stamp *Stamp
+}
+```
+
+### ID Operations
+
+```go
+// NewSeedID creates initial full ID (1)
+func NewSeedID() *ID {
+    return &ID{IsLeaf: true, Value: 1}
+}
+
+// Fork splits an ID into two
+func (id *ID) Fork() (*ID, *ID) {
+    if id.IsLeaf {
+        if id.Value == 0 {
+            // Cannot fork zero ID
+            return &ID{IsLeaf: true, Value: 0},
+                   &ID{IsLeaf: true, Value: 0}
+        }
+        // Split full ID into left and right halves
+        return &ID{
+                IsLeaf: false,
+                Left:   &ID{IsLeaf: true, Value: 1},
+                Right:  &ID{IsLeaf: true, Value: 0},
+            },
+            &ID{
+                IsLeaf: false,
+                Left:   &ID{IsLeaf: true, Value: 0},
+                Right:  &ID{IsLeaf: true, Value: 1},
+            }
+    }
+
+    // Fork from non-leaf: give half to each
+    if id.Left.IsLeaf && id.Left.Value == 0 {
+        // Left is zero, fork right
+        newRight1, newRight2 := id.Right.Fork()
+        return &ID{IsLeaf: false, Left: id.Left, Right: newRight1},
+               &ID{IsLeaf: false, Left: &ID{IsLeaf: true, Value: 0}, Right: newRight2}
+    }
+    if id.Right.IsLeaf && id.Right.Value == 0 {
+        // Right is zero, fork left
+        newLeft1, newLeft2 := id.Left.Fork()
+        return &ID{IsLeaf: false, Left: newLeft1, Right: id.Right},
+               &ID{IsLeaf: false, Left: newLeft2, Right: &ID{IsLeaf: true, Value: 0}}
+    }
+
+    // Both have IDs, split
+    return &ID{IsLeaf: false, Left: id.Left, Right: &ID{IsLeaf: true, Value: 0}},
+           &ID{IsLeaf: false, Left: &ID{IsLeaf: true, Value: 0}, Right: id.Right}
+}
+
+// Join merges two IDs
+func Join(id1, id2 *ID) *ID {
+    if id1.IsLeaf && id1.Value == 0 {
+        return id2
+    }
+    if id2.IsLeaf && id2.Value == 0 {
+        return id1
+    }
+    if id1.IsLeaf && id2.IsLeaf && id1.Value == 1 && id2.Value == 1 {
+        return &ID{IsLeaf: true, Value: 1}
+    }
+
+    // Normalize to non-leaf
+    left1 := id1.Left
+    right1 := id1.Right
+    left2 := id2.Left
+    right2 := id2.Right
+
+    if id1.IsLeaf {
+        left1 = id1
+        right1 = id1
+    }
+    if id2.IsLeaf {
+        left2 = id2
+        right2 = id2
+    }
+
+    newLeft := Join(left1, left2)
+    newRight := Join(right1, right2)
+
+    return normalize(&ID{IsLeaf: false, Left: newLeft, Right: newRight})
+}
+
+func normalize(id *ID) *ID {
+    if !id.IsLeaf {
+        if id.Left.IsLeaf && id.Right.IsLeaf &&
+           id.Left.Value == id.Right.Value {
+            return &ID{IsLeaf: true, Value: id.Left.Value}
+        }
+    }
+    return id
+}
+```
+
+### Stamp Operations
+
+```go
+// NewStamp creates initial stamp (0)
+func NewStamp() *Stamp {
+    return &Stamp{Base: 0}
+}
+
+// Event increments the stamp for the given ID
+func Event(id *ID, stamp *Stamp) *Stamp {
+    if id.IsLeaf {
+        if id.Value == 1 {
+            return &Stamp{Base: stamp.Base + 1}
+        }
+        return stamp // Cannot increment with zero ID
+    }
+
+    // Non-leaf ID: fill where we have ID
+    if id.Left.IsLeaf && id.Left.Value == 1 {
+        // Have left ID, increment left
+        newLeft := Event(&ID{IsLeaf: true, Value: 1}, getLeft(stamp))
+        return normalizeStamp(&Stamp{
+            Base:  stamp.Base,
+            Left:  newLeft,
+            Right: getRight(stamp),
+        })
+    }
+    if id.Right.IsLeaf && id.Right.Value == 1 {
+        newRight := Event(&ID{IsLeaf: true, Value: 1}, getRight(stamp))
+        return normalizeStamp(&Stamp{
+            Base:  stamp.Base,
+            Left:  getLeft(stamp),
+            Right: newRight,
+        })
+    }
+
+    // Both non-zero, choose lower side
+    leftMax := maxStamp(getLeft(stamp))
+    rightMax := maxStamp(getRight(stamp))
+
+    if leftMax <= rightMax {
+        return normalizeStamp(&Stamp{
+            Base:  stamp.Base,
+            Left:  Event(id.Left, getLeft(stamp)),
+            Right: getRight(stamp),
+        })
+    }
+    return normalizeStamp(&Stamp{
+        Base:  stamp.Base,
+        Left:  getLeft(stamp),
+        Right: Event(id.Right, getRight(stamp)),
+    })
+}
+
+func getLeft(s *Stamp) *Stamp {
+    if s.Left == nil {
+        return &Stamp{Base: 0}
+    }
+    return s.Left
+}
+
+func getRight(s *Stamp) *Stamp {
+    if s.Right == nil {
+        return &Stamp{Base: 0}
+    }
+    return s.Right
+}
+
+func maxStamp(s *Stamp) int {
+    if s.Left == nil && s.Right == nil {
+        return s.Base
+    }
+    left := 0
+    right := 0
+    if s.Left != nil {
+        left = maxStamp(s.Left)
+    }
+    if s.Right != nil {
+        right = maxStamp(s.Right)
+    }
+    max := left
+    if right > max {
+        max = right
+    }
+    return s.Base + max
+}
+
+// JoinStamps merges two stamps
+func JoinStamps(s1, s2 *Stamp) *Stamp {
+    // Take max at each level
+    base := s1.Base
+    if s2.Base > base {
+        base = s2.Base
+    }
+
+    // Adjust for base difference
+    adj1 := s1.Base
+    adj2 := s2.Base
+
+    return normalizeStamp(&Stamp{
+        Base:  base,
+        Left:  joinStampsRecursive(s1.Left, s2.Left, adj1-base, adj2-base),
+        Right: joinStampsRecursive(s1.Right, s2.Right, adj1-base, adj2-base),
+    })
+}
+
+func normalizeStamp(s *Stamp) *Stamp {
+    if s.Left == nil && s.Right == nil {
+        return s
+    }
+    if s.Left != nil && s.Right != nil {
+        if s.Left.Base > 0 && s.Right.Base > 0 {
+            min := s.Left.Base
+            if s.Right.Base < min {
+                min = s.Right.Base
+            }
+            return &Stamp{
+                Base:  s.Base + min,
+                Left:  &Stamp{Base: s.Left.Base - min, Left: s.Left.Left, Right: s.Left.Right},
+                Right: &Stamp{Base: s.Right.Base - min, Left: s.Right.Left, Right: s.Right.Right},
+            }
+        }
+    }
+    return s
+}
+```
+
+## Hybrid Logical Clock Implementation
+
+```go
+type HLC struct {
+    l  int64      // logical component (physical time)
+    c  int64      // counter
+    mu sync.Mutex
+}
+
+func NewHLC() *HLC {
+    return &HLC{l: 0, c: 0}
+}
+
+type HLCTimestamp struct {
+    L int64
+    C int64
+}
+
+func (hlc *HLC) physicalTime() int64 {
+    return time.Now().UnixNano()
+}
+
+// Now returns current HLC timestamp for local/send event
+func (hlc *HLC) Now() HLCTimestamp {
+    hlc.mu.Lock()
+    defer hlc.mu.Unlock()
+
+    pt := hlc.physicalTime()
+
+    if pt > hlc.l {
+        hlc.l = pt
+        hlc.c = 0
+    } else {
+        hlc.c++
+    }
+
+    return HLCTimestamp{L: hlc.l, C: hlc.c}
+}
+
+// Update updates HLC based on received timestamp
+func (hlc *HLC) Update(received HLCTimestamp) HLCTimestamp {
+    hlc.mu.Lock()
+    defer hlc.mu.Unlock()
+
+    pt := hlc.physicalTime()
+
+    if pt > hlc.l && pt > received.L {
+        hlc.l = pt
+        hlc.c = 0
+    } else if received.L > hlc.l {
+        hlc.l = received.L
+        hlc.c = received.C + 1
+    } else if hlc.l > received.L {
+        hlc.c++
+    } else { // hlc.l == received.L
+        if received.C > hlc.c {
+            hlc.c = received.C + 1
+        } else {
+            hlc.c++
+        }
+    }
+
+    return HLCTimestamp{L: hlc.l, C: hlc.c}
+}
+
+// Compare compares two HLC timestamps
+func (t1 HLCTimestamp) Compare(t2 HLCTimestamp) int {
+    if t1.L < t2.L {
+        return -1
+    }
+    if t1.L > t2.L {
+        return 1
+    }
+    if t1.C < t2.C {
+        return -1
+    }
+    if t1.C > t2.C {
+        return 1
+    }
+    return 0
+}
+```
+
+## Causal Broadcast Implementation
+
+```go
+type CausalBroadcast struct {
+    vc       *VectorClock
+    pending  []PendingMessage
+    deliver  func(Message)
+    mu       sync.Mutex
+}
+
+type PendingMessage struct {
+    Msg       Message
+    Timestamp map[string]uint64
+}
+
+func NewCausalBroadcast(processID string, processes []string, deliver func(Message)) *CausalBroadcast {
+    return &CausalBroadcast{
+        vc:      NewVectorClock(processID, processes),
+        pending: make([]PendingMessage, 0),
+        deliver: deliver,
+    }
+}
+
+// Broadcast sends a message to all processes
+func (cb *CausalBroadcast) Broadcast(msg Message) map[string]uint64 {
+    cb.mu.Lock()
+    defer cb.mu.Unlock()
+
+    timestamp := cb.vc.Send()
+    // Actual network broadcast would happen here
+    return timestamp
+}
+
+// Receive handles an incoming message
+func (cb *CausalBroadcast) Receive(msg Message, sender string, timestamp map[string]uint64) {
+    cb.mu.Lock()
+    defer cb.mu.Unlock()
+
+    // Add to pending
+    cb.pending = append(cb.pending, PendingMessage{Msg: msg, Timestamp: timestamp})
+
+    // Try to deliver pending messages
+    cb.tryDeliver()
+}
+
+func (cb *CausalBroadcast) tryDeliver() {
+    changed := true
+    for changed {
+        changed = false
+
+        for i, pending := range cb.pending {
+            if cb.canDeliver(pending.Timestamp) {
+                // Deliver message
+                cb.vc.Receive(pending.Timestamp)
+                cb.deliver(pending.Msg)
+
+                // Remove from pending
+                cb.pending = append(cb.pending[:i], cb.pending[i+1:]...)
+                changed = true
+                break
+            }
+        }
+    }
+}
+
+func (cb *CausalBroadcast) canDeliver(msgVC map[string]uint64) bool {
+    currentVC := cb.vc.clocks
+
+    for pid, msgTime := range msgVC {
+        if pid == cb.vc.self {
+            // Must be next expected from sender
+            if msgTime != currentVC[pid]+1 {
+                return false
+            }
+        } else {
+            // All other dependencies must be satisfied
+            if msgTime > currentVC[pid] {
+                return false
+            }
+        }
+    }
+    return true
+}
+```

.claude/skills/domain-driven-design/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: domain-driven-design
+description: This skill should be used when designing software architecture, modeling domains, reviewing code for DDD compliance, identifying bounded contexts, designing aggregates, or discussing strategic and tactical DDD patterns. Provides comprehensive Domain-Driven Design principles, axioms, heuristics, and anti-patterns for building maintainable, domain-centric software systems.
+---
+
+# Domain-Driven Design
+
+## Overview
+
+Domain-Driven Design (DDD) is an approach to software development that centers the design on the core business domain. This skill provides principles, patterns, and heuristics for both strategic design (system boundaries and relationships) and tactical design (code-level patterns).
+
+## When to Apply This Skill
+
+- Designing new systems or features with complex business logic
+- Identifying and defining bounded contexts
+- Modeling aggregates, entities, and value objects
+- Reviewing code for DDD pattern compliance
+- Decomposing monoliths into services
+- Establishing ubiquitous language with domain experts
+
+## Core Axioms
+
+### Axiom 1: The Domain is Supreme
+
+Software exists to solve domain problems. Technical decisions serve the domain, not vice versa. When technical elegance conflicts with domain clarity, domain clarity wins.
+
+### Axiom 2: Language Creates Reality
+
+The ubiquitous language shapes how teams think about the domain. Ambiguous language creates ambiguous software. Invest heavily in precise terminology.
+
+### Axiom 3: Boundaries Enable Autonomy
+
+Explicit boundaries (bounded contexts) allow teams to evolve independently. The cost of integration is worth the benefit of isolation.
+
+### Axiom 4: Models are Imperfect Approximations
+
+No model captures all domain complexity. Accept that models simplify reality. Refine models continuously as understanding deepens.
+
+## Strategic Design Quick Reference
+
+| Pattern | Purpose | Key Heuristic |
+|---------|---------|---------------|
+| **Bounded Context** | Define linguistic/model boundaries | One team, one language, one model |
+| **Context Map** | Document context relationships | Make implicit integrations explicit |
+| **Subdomain** | Classify domain areas by value | Core (invest), Supporting (adequate), Generic (outsource) |
+| **Ubiquitous Language** | Shared vocabulary | If experts don't use the term, neither should code |
+
+For detailed strategic patterns, consult `references/strategic-patterns.md`.
+
+## Tactical Design Quick Reference
+
+| Pattern | Purpose | Key Heuristic |
+|---------|---------|---------------|
+| **Entity** | Identity-tracked object | "Same identity = same thing" regardless of attributes |
+| **Value Object** | Immutable, identity-less | Equality by value, always immutable, self-validating |
+| **Aggregate** | Consistency boundary | Small aggregates, reference by ID, one transaction = one aggregate |
+| **Domain Event** | Record state changes | Past tense naming, immutable, contains all relevant data |
+| **Repository** | Collection abstraction | One per aggregate root, domain-focused interface |
+| **Domain Service** | Stateless operations | When logic doesn't belong to any single entity |
+| **Factory** | Complex object creation | When construction logic is complex or variable |
+
+For detailed tactical patterns, consult `references/tactical-patterns.md`.
+
+## Essential Heuristics
+
+### Aggregate Design Heuristics
+
+1. **Protect business invariants inside aggregate boundaries** - If two pieces of data must be consistent, they belong in the same aggregate
+2. **Design small aggregates** - Large aggregates cause concurrency issues and slow performance
+3. **Reference other aggregates by identity only** - Never hold direct object references across aggregate boundaries
+4. **Update one aggregate per transaction** - Eventual consistency across aggregates using domain events
+5. **Aggregate roots are the only entry point** - External code never reaches inside to manipulate child entities
+
+### Bounded Context Heuristics
+
+1. **Linguistic boundaries** - When the same word means different things, you have different contexts
+2. **Team boundaries** - One context per team enables autonomy
+3. **Process boundaries** - Different business processes often indicate different contexts
+4. **Data ownership** - Each context owns its data; no shared databases
+
+### Modeling Heuristics
+
+1. **Nouns → Entities or Value Objects** - Things with identity become entities; descriptive things become value objects
+2. **Verbs → Domain Services or Methods** - Actions become methods on entities or stateless services
+3. **Business rules → Invariants** - Rules the domain must always satisfy become aggregate invariants
+4. **Events in domain expert language → Domain Events** - "When X happens" becomes a domain event
+
+## Decision Guides
+
+### Entity vs Value Object
+
+```
+Does this thing have a lifecycle and identity that matters?
+├─ YES → Is identity based on an ID (not attributes)?
+│        ├─ YES → Entity
+│        └─ NO  → Reconsider; might be Value Object with natural key
+└─ NO  → Value Object
+```
+
+### Where Does This Logic Belong?
+
+```
+Is this logic stateless?
+├─ NO  → Does it belong to a single aggregate?
+│        ├─ YES → Method on the aggregate/entity
+│        └─ NO  → Reconsider aggregate boundaries
+└─ YES → Does it coordinate multiple aggregates?
+         ├─ YES → Application Service
+         └─ NO  → Does it represent a domain concept?
+                  ├─ YES → Domain Service
+                  └─ NO  → Infrastructure Service
+```
+
+### Should This Be a Separate Bounded Context?
+
+```
+Do different stakeholders use different language for this?
+├─ YES → Separate bounded context
+└─ NO  → Does a different team own this?
+         ├─ YES → Separate bounded context
+         └─ NO  → Would a separate model reduce complexity?
+                  ├─ YES → Consider separation (but weigh integration cost)
+                  └─ NO  → Keep in current context
+```
+
+## Anti-Patterns Overview
+
+| Anti-Pattern | Description | Fix |
+|--------------|-------------|-----|
+| **Anemic Domain Model** | Entities with only getters/setters | Move behavior into domain objects |
+| **Big Ball of Mud** | No clear boundaries | Identify bounded contexts |
+| **Smart UI** | Business logic in presentation layer | Extract domain layer |
+| **Database-Driven Design** | Model follows database schema | Model follows domain, map to database |
+| **Leaky Abstractions** | Infrastructure concerns in domain | Dependency inversion, ports and adapters |
+| **God Aggregate** | One aggregate does everything | Split by invariant boundaries |
+| **Premature Abstraction** | Abstracting before understanding | Concrete first, abstract when patterns emerge |
+
+For detailed anti-patterns and remediation, consult `references/anti-patterns.md`.
+
+## Implementation Checklist
+
+When implementing DDD in a codebase:
+
+- [ ] Ubiquitous language documented and used consistently in code
+- [ ] Bounded contexts identified with clear boundaries
+- [ ] Context map documenting integration patterns
+- [ ] Aggregates designed small with clear invariants
+- [ ] Entities have behavior, not just data
+- [ ] Value objects are immutable and self-validating
+- [ ] Domain events capture important state changes
+- [ ] Repositories abstract persistence for aggregate roots
+- [ ] No business logic in application services (orchestration only)
+- [ ] No infrastructure concerns in domain layer
+
+## Resources
+
+### references/
+
+- `strategic-patterns.md` - Detailed strategic DDD patterns including bounded contexts, context maps, subdomain classification, and ubiquitous language
+- `tactical-patterns.md` - Detailed tactical DDD patterns including entities, value objects, aggregates, domain events, repositories, and services
+- `anti-patterns.md` - Common DDD anti-patterns, how to identify them, and remediation strategies
+
+To search references for specific topics:
+- Bounded contexts: `grep -i "bounded context" references/`
+- Aggregate design: `grep -i "aggregate" references/`
+- Value objects: `grep -i "value object" references/`

.claude/skills/domain-driven-design/references/anti-patterns.md

@@ -0,0 +1,853 @@
+# DDD Anti-Patterns
+
+This reference documents common anti-patterns encountered when implementing Domain-Driven Design, how to identify them, and remediation strategies.
+
+## Anemic Domain Model
+
+### Description
+
+Entities that are mere data containers with getters and setters, while all business logic lives in "service" classes. The domain model looks like a relational database schema mapped to objects.
+
+### Symptoms
+
+- Entities with only get/set methods and no behavior
+- Service classes with methods like `orderService.calculateTotal(order)`
+- Business rules scattered across multiple services
+- Heavy use of DTOs that mirror entity structure
+- "Transaction scripts" in application services
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Anemic domain model
+class Order {
+  id: string;
+  customerId: string;
+  items: OrderItem[];
+  status: string;
+  total: number;
+
+  // Only data access, no behavior
+  getId(): string { return this.id; }
+  setStatus(status: string): void { this.status = status; }
+  getItems(): OrderItem[] { return this.items; }
+  setTotal(total: number): void { this.total = total; }
+}
+
+class OrderService {
+  // All logic external to the entity
+  calculateTotal(order: Order): number {
+    let total = 0;
+    for (const item of order.getItems()) {
+      total += item.price * item.quantity;
+    }
+    order.setTotal(total);
+    return total;
+  }
+
+  canShip(order: Order): boolean {
+    return order.status === 'PAID' && order.getItems().length > 0;
+  }
+
+  ship(order: Order, trackingNumber: string): void {
+    if (!this.canShip(order)) {
+      throw new Error('Cannot ship order');
+    }
+    order.setStatus('SHIPPED');
+    order.trackingNumber = trackingNumber;
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Rich domain model
+class Order {
+  private _id: OrderId;
+  private _items: OrderItem[];
+  private _status: OrderStatus;
+
+  // Behavior lives in the entity
+  get total(): Money {
+    return this._items.reduce(
+      (sum, item) => sum.add(item.subtotal()),
+      Money.zero()
+    );
+  }
+
+  canShip(): boolean {
+    return this._status === OrderStatus.Paid && this._items.length > 0;
+  }
+
+  ship(trackingNumber: TrackingNumber): void {
+    if (!this.canShip()) {
+      throw new OrderNotShippableError(this._id, this._status);
+    }
+    this._status = OrderStatus.Shipped;
+    this._trackingNumber = trackingNumber;
+  }
+
+  addItem(item: OrderItem): void {
+    this.ensureCanModify();
+    this._items.push(item);
+  }
+}
+
+// Application service is thin - only orchestration
+class OrderApplicationService {
+  async shipOrder(orderId: OrderId, trackingNumber: TrackingNumber): Promise<void> {
+    const order = await this.orderRepository.findById(orderId);
+    order.ship(trackingNumber);  // Domain logic in entity
+    await this.orderRepository.save(order);
+  }
+}
+```
+
+### Root Causes
+
+- Developers treating objects as data structures
+- Thinking in terms of database tables
+- Copying patterns from CRUD applications
+- Misunderstanding "service" to mean "all logic goes here"
+
+## God Aggregate
+
+### Description
+
+An aggregate that has grown to encompass too much. It handles multiple concerns, has many child entities, and becomes a performance and concurrency bottleneck.
+
+### Symptoms
+
+- Aggregates with 10+ child entity types
+- Long load times due to eager loading everything
+- Frequent optimistic concurrency conflicts
+- Methods that only touch a small subset of the aggregate
+- Difficulty reasoning about invariants
+
+### Example
+
+```typescript
+// ANTI-PATTERN: God aggregate
+class Customer {
+  private _id: CustomerId;
+  private _profile: CustomerProfile;
+  private _addresses: Address[];
+  private _paymentMethods: PaymentMethod[];
+  private _orders: Order[];           // History of all orders!
+  private _wishlist: WishlistItem[];
+  private _reviews: Review[];
+  private _loyaltyPoints: LoyaltyAccount;
+  private _preferences: Preferences;
+  private _notifications: Notification[];
+  private _supportTickets: SupportTicket[];
+
+  // Loading this customer loads EVERYTHING
+  // Updating preferences causes concurrency conflict with order placement
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Small, focused aggregates
+class Customer {
+  private _id: CustomerId;
+  private _profile: CustomerProfile;
+  private _defaultAddressId: AddressId;
+  private _membershipTier: MembershipTier;
+}
+
+class CustomerAddressBook {
+  private _customerId: CustomerId;
+  private _addresses: Address[];
+}
+
+class ShoppingCart {
+  private _customerId: CustomerId;  // Reference by ID
+  private _items: CartItem[];
+}
+
+class Wishlist {
+  private _customerId: CustomerId;  // Reference by ID
+  private _items: WishlistItem[];
+}
+
+class LoyaltyAccount {
+  private _customerId: CustomerId;  // Reference by ID
+  private _points: Points;
+  private _transactions: LoyaltyTransaction[];
+}
+```
+
+### Identification Heuristic
+
+Ask: "Do all these things need to be immediately consistent?" If the answer is no, they probably belong in separate aggregates.
+
+## Aggregate Reference Violation
+
+### Description
+
+Aggregates holding direct object references to other aggregates instead of referencing by identity. Creates implicit coupling and makes it impossible to reason about transactional boundaries.
+
+### Symptoms
+
+- Navigation from one aggregate to another: `order.customer.address`
+- Loading an aggregate brings in connected aggregates
+- Unclear what gets saved when calling `save()`
+- Difficulty implementing eventual consistency
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Direct reference
+class Order {
+  private customer: Customer;  // Direct reference!
+  private shippingAddress: Address;
+
+  getCustomerEmail(): string {
+    return this.customer.email;  // Navigating through!
+  }
+
+  validate(): void {
+    // Touching another aggregate's data
+    if (this.customer.creditLimit < this.total) {
+      throw new Error('Credit limit exceeded');
+    }
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Reference by identity
+class Order {
+  private _customerId: CustomerId;  // ID only!
+  private _shippingAddress: Address;  // Value object copied at order time
+
+  // If customer data is needed, it must be explicitly loaded
+  static create(
+    customerId: CustomerId,
+    shippingAddress: Address,
+    creditLimit: Money  // Passed in, not navigated to
+  ): Order {
+    return new Order(customerId, shippingAddress, creditLimit);
+  }
+}
+
+// Application service coordinates loading if needed
+class OrderApplicationService {
+  async getOrderWithCustomerDetails(orderId: OrderId): Promise<OrderDetails> {
+    const order = await this.orderRepository.findById(orderId);
+    const customer = await this.customerRepository.findById(order.customerId);
+
+    return new OrderDetails(order, customer);
+  }
+}
+```
+
+## Smart UI
+
+### Description
+
+Business logic embedded directly in the user interface layer. Controllers, presenters, or UI components contain domain rules.
+
+### Symptoms
+
+- Validation logic in form handlers
+- Business calculations in controllers
+- State machines in UI components
+- Domain rules duplicated across different UI views
+- "If we change the UI framework, we lose the business logic"
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Smart UI
+class OrderController {
+  submitOrder(request: Request): Response {
+    const cart = request.body;
+
+    // Business logic in controller!
+    let total = 0;
+    for (const item of cart.items) {
+      total += item.price * item.quantity;
+    }
+
+    // Discount rules in controller!
+    if (cart.items.length > 10) {
+      total *= 0.9;  // 10% bulk discount
+    }
+
+    if (total > 1000 && !this.hasValidPaymentMethod(cart.customerId)) {
+      return Response.error('Orders over $1000 require verified payment');
+    }
+
+    // More business rules...
+    const order = {
+      customerId: cart.customerId,
+      items: cart.items,
+      total: total,
+      status: 'PENDING'
+    };
+
+    this.database.insert('orders', order);
+    return Response.ok(order);
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: UI delegates to domain
+class OrderController {
+  submitOrder(request: Request): Response {
+    const command = new PlaceOrderCommand(
+      request.body.customerId,
+      request.body.items
+    );
+
+    try {
+      const orderId = this.orderApplicationService.placeOrder(command);
+      return Response.ok({ orderId });
+    } catch (error) {
+      if (error instanceof DomainError) {
+        return Response.badRequest(error.message);
+      }
+      throw error;
+    }
+  }
+}
+
+// Domain logic in domain layer
+class Order {
+  private calculateTotal(): Money {
+    const subtotal = this._items.reduce(
+      (sum, item) => sum.add(item.subtotal()),
+      Money.zero()
+    );
+    return this._discountPolicy.apply(subtotal, this._items.length);
+  }
+}
+
+class BulkDiscountPolicy implements DiscountPolicy {
+  apply(subtotal: Money, itemCount: number): Money {
+    if (itemCount > 10) {
+      return subtotal.multiply(0.9);
+    }
+    return subtotal;
+  }
+}
+```
+
+## Database-Driven Design
+
+### Description
+
+The domain model is derived from the database schema rather than from domain concepts. Tables become classes; foreign keys become object references; database constraints become business rules.
+
+### Symptoms
+
+- Class names match table names exactly
+- Foreign key relationships drive object graph
+- ID fields everywhere, even where identity doesn't matter
+- `nullable` database columns drive optional properties
+- Domain model changes require database migration first
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Database-driven model
+// Mirrors database schema exactly
+class orders {
+  order_id: number;
+  customer_id: number;
+  order_date: Date;
+  status_cd: string;
+  shipping_address_id: number;
+  billing_address_id: number;
+  total_amt: number;
+  tax_amt: number;
+  created_ts: Date;
+  updated_ts: Date;
+}
+
+class order_items {
+  order_item_id: number;
+  order_id: number;
+  product_id: number;
+  quantity: number;
+  unit_price: number;
+  discount_pct: number;
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Domain-driven model
+class Order {
+  private readonly _id: OrderId;
+  private _status: OrderStatus;
+  private _items: OrderItem[];
+  private _shippingAddress: Address;  // Value object, not FK
+  private _billingAddress: Address;
+
+  // Domain behavior, not database structure
+  get total(): Money {
+    return this._items.reduce(
+      (sum, item) => sum.add(item.lineTotal()),
+      Money.zero()
+    );
+  }
+
+  ship(trackingNumber: TrackingNumber): void {
+    // Business logic
+  }
+}
+
+// Mapping is infrastructure concern
+class OrderRepository {
+  async save(order: Order): Promise<void> {
+    // Map rich domain object to database tables
+    await this.db.query(
+      'INSERT INTO orders (id, status, shipping_street, shipping_city...) VALUES (...)'
+    );
+  }
+}
+```
+
+### Key Principle
+
+The domain model reflects how domain experts think, not how data is stored. Persistence is an infrastructure detail.
+
+## Leaky Abstractions
+
+### Description
+
+Infrastructure concerns bleeding into the domain layer. Domain objects depend on frameworks, databases, or external services.
+
+### Symptoms
+
+- Domain entities with ORM decorators
+- Repository interfaces returning database-specific types
+- Domain services making HTTP calls
+- Framework annotations on domain objects
+- `import { Entity } from 'typeorm'` in domain layer
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Infrastructure leaking into domain
+import { Entity, Column, PrimaryColumn, ManyToOne } from 'typeorm';
+import { IsEmail, IsNotEmpty } from 'class-validator';
+
+@Entity('customers')  // ORM in domain!
+export class Customer {
+  @PrimaryColumn()
+  id: string;
+
+  @Column()
+  @IsNotEmpty()  // Validation framework in domain!
+  name: string;
+
+  @Column()
+  @IsEmail()
+  email: string;
+
+  @ManyToOne(() => Subscription)  // ORM relationship in domain!
+  subscription: Subscription;
+}
+
+// Domain service calling external API directly
+class ShippingCostService {
+  async calculateCost(order: Order): Promise<number> {
+    // HTTP call in domain!
+    const response = await fetch('https://shipping-api.com/rates', {
+      body: JSON.stringify(order)
+    });
+    return response.json().cost;
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Clean domain layer
+// Domain object - no framework dependencies
+class Customer {
+  private constructor(
+    private readonly _id: CustomerId,
+    private readonly _name: CustomerName,
+    private readonly _email: Email
+  ) {}
+
+  static create(name: string, email: string): Customer {
+    return new Customer(
+      CustomerId.generate(),
+      CustomerName.create(name),  // Self-validating value object
+      Email.create(email)         // Self-validating value object
+    );
+  }
+}
+
+// Port (interface) defined in domain
+interface ShippingRateProvider {
+  getRate(destination: Address, weight: Weight): Promise<Money>;
+}
+
+// Domain service uses port
+class ShippingCostCalculator {
+  constructor(private rateProvider: ShippingRateProvider) {}
+
+  async calculate(order: Order): Promise<Money> {
+    return this.rateProvider.getRate(
+      order.shippingAddress,
+      order.totalWeight()
+    );
+  }
+}
+
+// Adapter (infrastructure) implements port
+class ShippingApiRateProvider implements ShippingRateProvider {
+  async getRate(destination: Address, weight: Weight): Promise<Money> {
+    const response = await fetch('https://shipping-api.com/rates', {
+      body: JSON.stringify({ destination, weight })
+    });
+    const data = await response.json();
+    return Money.of(data.cost, Currency.USD);
+  }
+}
+```
+
+## Shared Database
+
+### Description
+
+Multiple bounded contexts accessing the same database tables. Changes in one context break others. No clear data ownership.
+
+### Symptoms
+
+- Multiple services querying the same tables
+- Fear of schema changes because "something else might break"
+- Unclear which service is authoritative for data
+- Cross-context joins in queries
+- Database triggers coordinating contexts
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Shared database
+// Sales context
+class SalesOrderService {
+  async getOrder(orderId: string) {
+    return this.db.query(`
+      SELECT o.*, c.name, c.email, p.name as product_name
+      FROM orders o
+      JOIN customers c ON o.customer_id = c.id
+      JOIN products p ON o.product_id = p.id
+      WHERE o.id = ?
+    `, [orderId]);
+  }
+}
+
+// Shipping context - same tables!
+class ShippingService {
+  async getOrdersToShip() {
+    return this.db.query(`
+      SELECT o.*, c.address
+      FROM orders o
+      JOIN customers c ON o.customer_id = c.id
+      WHERE o.status = 'PAID'
+    `);
+  }
+
+  async markShipped(orderId: string) {
+    // Directly modifying shared table
+    await this.db.query(
+      "UPDATE orders SET status = 'SHIPPED' WHERE id = ?",
+      [orderId]
+    );
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Each context owns its data
+// Sales context - owns order creation
+class SalesOrderRepository {
+  async save(order: SalesOrder): Promise<void> {
+    await this.salesDb.query('INSERT INTO sales_orders...');
+
+    // Publish event for other contexts
+    await this.eventPublisher.publish(
+      new OrderPlaced(order.id, order.customerId, order.items)
+    );
+  }
+}
+
+// Shipping context - owns its projection
+class ShippingOrderProjection {
+  // Handles events to build local projection
+  async handleOrderPlaced(event: OrderPlaced): Promise<void> {
+    await this.shippingDb.query(`
+      INSERT INTO shipments (order_id, customer_id, status)
+      VALUES (?, ?, 'PENDING')
+    `, [event.orderId, event.customerId]);
+  }
+}
+
+class ShipmentRepository {
+  async findPendingShipments(): Promise<Shipment[]> {
+    // Queries only shipping context's data
+    return this.shippingDb.query(
+      "SELECT * FROM shipments WHERE status = 'PENDING'"
+    );
+  }
+}
+```
+
+## Premature Abstraction
+
+### Description
+
+Creating abstractions, interfaces, and frameworks before understanding the problem space. Often justified as "flexibility for the future."
+
+### Symptoms
+
+- Interfaces with single implementations
+- Generic frameworks solving hypothetical problems
+- Heavy use of design patterns without clear benefit
+- Configuration systems for things that never change
+- "We might need this someday"
+
+### Example
+
+```typescript
+// ANTI-PATTERN: Premature abstraction
+interface IOrderProcessor<TOrder, TResult> {
+  process(order: TOrder): Promise<TResult>;
+}
+
+interface IOrderValidator<TOrder> {
+  validate(order: TOrder): ValidationResult;
+}
+
+interface IOrderPersister<TOrder> {
+  persist(order: TOrder): Promise<void>;
+}
+
+abstract class AbstractOrderProcessor<TOrder, TResult>
+  implements IOrderProcessor<TOrder, TResult> {
+
+  constructor(
+    protected validator: IOrderValidator<TOrder>,
+    protected persister: IOrderPersister<TOrder>,
+    protected notifier: INotificationService,
+    protected logger: ILogger,
+    protected metrics: IMetricsCollector
+  ) {}
+
+  async process(order: TOrder): Promise<TResult> {
+    this.logger.log('Processing order');
+    this.metrics.increment('orders.processed');
+
+    const validation = this.validator.validate(order);
+    if (!validation.isValid) {
+      throw new ValidationException(validation.errors);
+    }
+
+    const result = await this.doProcess(order);
+    await this.persister.persist(order);
+    await this.notifier.notify(order);
+
+    return result;
+  }
+
+  protected abstract doProcess(order: TOrder): Promise<TResult>;
+}
+
+// Only one concrete implementation ever created
+class StandardOrderProcessor extends AbstractOrderProcessor<Order, OrderResult> {
+  protected async doProcess(order: Order): Promise<OrderResult> {
+    // The actual logic is trivial
+    return new OrderResult(order.id);
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Concrete first, abstract when patterns emerge
+class OrderService {
+  async placeOrder(command: PlaceOrderCommand): Promise<OrderId> {
+    const order = Order.create(command);
+
+    if (!order.isValid()) {
+      throw new InvalidOrderError(order.validationErrors());
+    }
+
+    await this.orderRepository.save(order);
+
+    return order.id;
+  }
+}
+
+// Only add abstraction when you have multiple implementations
+// and understand the variation points
+```
+
+### Heuristic
+
+Wait until you have three similar implementations before abstracting. The right abstraction will be obvious then.
+
+## Big Ball of Mud
+
+### Description
+
+A system without clear architectural boundaries. Everything depends on everything. Changes ripple unpredictably.
+
+### Symptoms
+
+- No clear module boundaries
+- Circular dependencies
+- Any change might break anything
+- "Only Bob understands how this works"
+- Integration tests are the only reliable tests
+- Fear of refactoring
+
+### Identification
+
+```
+# Circular dependency example
+OrderService → CustomerService → PaymentService → OrderService
+```
+
+### Remediation Strategy
+
+1. **Identify implicit contexts** - Find clusters of related functionality
+2. **Define explicit boundaries** - Create modules/packages with clear interfaces
+3. **Break cycles** - Introduce events or shared kernel for circular dependencies
+4. **Enforce boundaries** - Use architectural tests, linting rules
+
+```typescript
+// Step 1: Identify boundaries
+// sales/ - order creation, pricing
+// fulfillment/ - shipping, tracking
+// customer/ - customer management
+// shared/ - shared kernel (Money, Address)
+
+// Step 2: Define public interfaces
+// sales/index.ts
+export { OrderService } from './application/OrderService';
+export { OrderPlaced, OrderCancelled } from './domain/events';
+// Internal types not exported
+
+// Step 3: Break cycles with events
+class OrderService {
+  async placeOrder(command: PlaceOrderCommand): Promise<OrderId> {
+    const order = Order.create(command);
+    await this.orderRepository.save(order);
+
+    // Instead of calling PaymentService directly
+    await this.eventPublisher.publish(new OrderPlaced(order));
+
+    return order.id;
+  }
+}
+
+class PaymentEventHandler {
+  async handleOrderPlaced(event: OrderPlaced): Promise<void> {
+    await this.paymentService.collectPayment(event.orderId, event.total);
+  }
+}
+```
+
+## CRUD-Driven Development
+
+### Description
+
+Treating all domain operations as Create, Read, Update, Delete operations. Loses domain intent and behavior.
+
+### Symptoms
+
+- Endpoints like `PUT /orders/{id}` that accept any field changes
+- Service methods like `updateOrder(orderId, updates)`
+- Domain events named `OrderUpdated` instead of `OrderShipped`
+- No validation of state transitions
+- Business operations hidden behind generic updates
+
+### Example
+
+```typescript
+// ANTI-PATTERN: CRUD-driven
+class OrderController {
+  @Put('/orders/:id')
+  async updateOrder(id: string, body: Partial<Order>) {
+    // Any field can be updated!
+    return this.orderService.update(id, body);
+  }
+}
+
+class OrderService {
+  async update(id: string, updates: Partial<Order>): Promise<Order> {
+    const order = await this.repo.findById(id);
+    Object.assign(order, updates);  // Blindly apply updates
+    return this.repo.save(order);
+  }
+}
+```
+
+### Remediation
+
+```typescript
+// CORRECT: Intent-revealing operations
+class OrderController {
+  @Post('/orders/:id/ship')
+  async shipOrder(id: string, body: ShipOrderRequest) {
+    return this.orderService.ship(id, body.trackingNumber);
+  }
+
+  @Post('/orders/:id/cancel')
+  async cancelOrder(id: string, body: CancelOrderRequest) {
+    return this.orderService.cancel(id, body.reason);
+  }
+}
+
+class OrderService {
+  async ship(orderId: OrderId, trackingNumber: TrackingNumber): Promise<void> {
+    const order = await this.repo.findById(orderId);
+    order.ship(trackingNumber);  // Domain logic with validation
+    await this.repo.save(order);
+    await this.publish(new OrderShipped(orderId, trackingNumber));
+  }
+
+  async cancel(orderId: OrderId, reason: CancellationReason): Promise<void> {
+    const order = await this.repo.findById(orderId);
+    order.cancel(reason);  // Validates cancellation is allowed
+    await this.repo.save(order);
+    await this.publish(new OrderCancelled(orderId, reason));
+  }
+}
+```
+
+## Summary: Detection Checklist
+
+| Anti-Pattern | Key Question |
+|--------------|--------------|
+| Anemic Domain Model | Do entities have behavior or just data? |
+| God Aggregate | Does everything need immediate consistency? |
+| Aggregate Reference Violation | Are aggregates holding other aggregates? |
+| Smart UI | Would changing UI framework lose business logic? |
+| Database-Driven Design | Does model match tables or domain concepts? |
+| Leaky Abstractions | Does domain code import infrastructure? |
+| Shared Database | Do multiple contexts write to same tables? |
+| Premature Abstraction | Are there interfaces with single implementations? |
+| Big Ball of Mud | Can any change break anything? |
+| CRUD-Driven Development | Are operations generic updates or domain intents? |

.claude/skills/domain-driven-design/references/strategic-patterns.md

@@ -0,0 +1,358 @@
+# Strategic DDD Patterns
+
+Strategic DDD patterns address the large-scale structure of a system: how to divide it into bounded contexts, how those contexts relate, and how to prioritize investment across subdomains.
+
+## Bounded Context
+
+### Definition
+
+A Bounded Context is an explicit boundary within which a domain model exists. Inside the boundary, all terms have specific, unambiguous meanings. The same term may mean different things in different bounded contexts.
+
+### Why It Matters
+
+- **Linguistic clarity** - "Customer" in Sales means something different than "Customer" in Shipping
+- **Model isolation** - Changes to one model don't cascade across the system
+- **Team autonomy** - Teams can work independently within their context
+- **Focused complexity** - Each context solves one set of problems well
+
+### Identification Heuristics
+
+1. **Language divergence** - When stakeholders use the same word differently, there's a context boundary
+2. **Department boundaries** - Organizational structure often mirrors domain structure
+3. **Process boundaries** - End-to-end business processes often define context edges
+4. **Data ownership** - Who is the authoritative source for this data?
+5. **Change frequency** - Parts that change together should stay together
+
+### Example: E-Commerce Platform
+
+| Context | "Order" means... | "Product" means... |
+|---------|------------------|-------------------|
+| **Catalog** | N/A | Displayable item with description, images, categories |
+| **Inventory** | N/A | Stock keeping unit with quantity and location |
+| **Sales** | Shopping cart ready for checkout | Line item with price |
+| **Fulfillment** | Shipment to be picked and packed | Physical item to ship |
+| **Billing** | Invoice to collect payment | Taxable good |
+
+### Implementation Patterns
+
+#### Separate Deployables
+Each bounded context as its own service/application.
+
+```
+catalog-service/
+├── src/domain/Product.ts
+└── src/infrastructure/CatalogRepository.ts
+
+sales-service/
+├── src/domain/Product.ts    # Different model!
+└── src/domain/Order.ts
+```
+
+#### Module Boundaries
+Bounded contexts as modules within a monolith.
+
+```
+src/
+├── catalog/
+│   └── domain/Product.ts
+├── sales/
+│   └── domain/Product.ts    # Different model!
+└── shared/
+    └── kernel/Money.ts      # Shared kernel
+```
+
+## Context Map
+
+### Definition
+
+A Context Map is a visual and documented representation of how bounded contexts relate to each other. It makes integration patterns explicit.
+
+### Integration Patterns
+
+#### Partnership
+
+Two contexts develop together with mutual dependencies. Changes are coordinated.
+
+```
+┌─────────────┐     Partnership     ┌─────────────┐
+│   Catalog   │◄──────────────────►│  Inventory  │
+└─────────────┘                     └─────────────┘
+```
+
+**Use when**: Two teams must succeed or fail together.
+
+#### Shared Kernel
+
+A small, shared model that multiple contexts depend on. Changes require agreement from all consumers.
+
+```
+┌─────────────┐                    ┌─────────────┐
+│    Sales    │                    │   Billing   │
+└──────┬──────┘                    └──────┬──────┘
+       │                                  │
+       └─────────►  Money  ◄──────────────┘
+                   (shared kernel)
+```
+
+**Use when**: Core concepts genuinely need the same model.
+**Danger**: Creates coupling. Keep shared kernels minimal.
+
+#### Customer-Supplier
+
+Upstream context (supplier) provides data/services; downstream context (customer) consumes. Supplier considers customer needs.
+
+```
+┌─────────────┐                    ┌─────────────┐
+│   Catalog   │───── supplies ────►│    Sales    │
+│  (upstream) │                    │ (downstream)│
+└─────────────┘                    └─────────────┘
+```
+
+**Use when**: One context clearly serves another, and the supplier is responsive.
+
+#### Conformist
+
+Downstream adopts upstream's model without negotiation. Upstream doesn't accommodate downstream needs.
+
+```
+┌─────────────┐                    ┌─────────────┐
+│ External    │───── dictates ────►│  Our App    │
+│    API      │                    │ (conformist)│
+└─────────────┘                    └─────────────┘
+```
+
+**Use when**: Upstream won't change (third-party API), and their model is acceptable.
+
+#### Anti-Corruption Layer (ACL)
+
+Translation layer that protects a context from external models. Transforms data at the boundary.
+
+```
+┌─────────────┐        ┌───────┐        ┌─────────────┐
+│   Legacy    │───────►│  ACL  │───────►│  New System │
+│   System    │        └───────┘        └─────────────┘
+```
+
+**Use when**: Upstream model would pollute downstream; translation is worth the cost.
+
+```typescript
+// Anti-Corruption Layer example
+class LegacyOrderAdapter {
+  constructor(private legacyApi: LegacyOrderApi) {}
+
+  translateOrder(legacyOrder: LegacyOrder): Order {
+    return new Order({
+      id: OrderId.from(legacyOrder.order_num),
+      customer: this.translateCustomer(legacyOrder.cust_data),
+      items: legacyOrder.line_items.map(this.translateLineItem),
+      // Transform legacy status codes to domain concepts
+      status: this.mapStatus(legacyOrder.stat_cd),
+    });
+  }
+
+  private mapStatus(legacyCode: string): OrderStatus {
+    const mapping: Record<string, OrderStatus> = {
+      'OP': OrderStatus.Open,
+      'SH': OrderStatus.Shipped,
+      'CL': OrderStatus.Closed,
+    };
+    return mapping[legacyCode] ?? OrderStatus.Unknown;
+  }
+}
+```
+
+#### Open Host Service
+
+A context provides a well-defined protocol/API for others to consume.
+
+```
+                    ┌─────────────┐
+        ┌──────────►│   Reports   │
+        │           └─────────────┘
+┌───────┴───────┐   ┌─────────────┐
+│ Catalog API   │──►│   Search    │
+│ (open host)   │   └─────────────┘
+└───────┬───────┘   ┌─────────────┐
+        └──────────►│   Partner   │
+                    └─────────────┘
+```
+
+**Use when**: Multiple downstream contexts need access; worth investing in a stable API.
+
+#### Published Language
+
+A shared language format (schema) for communication between contexts. Often combined with Open Host Service.
+
+Examples: JSON schemas, Protocol Buffers, GraphQL schemas, industry standards (HL7 for healthcare).
+
+#### Separate Ways
+
+Contexts have no integration. Each solves its needs independently.
+
+**Use when**: Integration cost exceeds benefit; duplication is acceptable.
+
+### Context Map Notation
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                      CONTEXT MAP                              │
+├───────────────────────────────────────────────────────────────┤
+│                                                               │
+│  ┌─────────┐         Partnership          ┌─────────┐        │
+│  │ Sales   │◄────────────────────────────►│Inventory│        │
+│  │  (U,D)  │                              │  (U,D)  │        │
+│  └────┬────┘                              └────┬────┘        │
+│       │                                        │              │
+│       │ Customer/Supplier                      │              │
+│       ▼                                        │              │
+│  ┌─────────┐                                   │              │
+│  │ Billing │◄──────────────────────────────────┘              │
+│  │   (D)   │         Conformist                               │
+│  └─────────┘                                                  │
+│                                                               │
+│  Legend: U = Upstream, D = Downstream                         │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Subdomain Classification
+
+### Core Domain
+
+The essential differentiator. This is where competitive advantage lives.
+
+**Characteristics**:
+- Unique to this business
+- Complex, requires deep expertise
+- Frequently changing as business evolves
+- Worth significant investment
+
+**Strategy**: Build in-house with best talent. Invest heavily in modeling.
+
+### Supporting Subdomain
+
+Necessary for the business but not a differentiator.
+
+**Characteristics**:
+- Important but not unique
+- Moderate complexity
+- Changes less frequently
+- Custom implementation needed
+
+**Strategy**: Build with adequate (not exceptional) investment. May outsource.
+
+### Generic Subdomain
+
+Solved problems with off-the-shelf solutions.
+
+**Characteristics**:
+- Common across industries
+- Well-understood solutions exist
+- Rarely changes
+- Not a differentiator
+
+**Strategy**: Buy or use open-source. Don't reinvent.
+
+### Example: E-Commerce Platform
+
+| Subdomain | Type | Strategy |
+|-----------|------|----------|
+| Product Recommendation Engine | Core | In-house, top talent |
+| Inventory Management | Supporting | Build, adequate investment |
+| Payment Processing | Generic | Third-party (Stripe, etc.) |
+| User Authentication | Generic | Third-party or standard library |
+| Shipping Logistics | Supporting | Build or integrate vendor |
+| Customer Analytics | Core | In-house, strategic investment |
+
+## Ubiquitous Language
+
+### Definition
+
+A common language shared by developers and domain experts. It appears in conversations, documentation, and code.
+
+### Building Ubiquitous Language
+
+1. **Listen to experts** - Use their terminology, not technical jargon
+2. **Challenge vague terms** - "Process the order" → What exactly happens?
+3. **Document glossary** - Maintain a living dictionary
+4. **Enforce in code** - Class and method names use the language
+5. **Refine continuously** - Language evolves with understanding
+
+### Language in Code
+
+```typescript
+// Bad: Technical terms
+class OrderProcessor {
+  handleOrderCreation(data: OrderData): void {
+    this.validateData(data);
+    this.persistToDatabase(data);
+    this.sendNotification(data);
+  }
+}
+
+// Good: Ubiquitous language
+class OrderTaker {
+  placeOrder(cart: ShoppingCart): PlacedOrder {
+    const order = cart.checkout();
+    order.confirmWith(this.paymentGateway);
+    this.orderRepository.save(order);
+    this.domainEvents.publish(new OrderPlaced(order));
+    return order;
+  }
+}
+```
+
+### Glossary Example
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Order** | A confirmed purchase with payment collected | Sales |
+| **Shipment** | Physical package(s) sent to fulfill an order | Fulfillment |
+| **SKU** | Stock Keeping Unit; unique identifier for inventory | Inventory |
+| **Cart** | Uncommitted collection of items a customer intends to buy | Sales |
+| **Listing** | Product displayed for purchase in the catalog | Catalog |
+
+### Anti-Pattern: Technical Language Leakage
+
+```typescript
+// Bad: Database terminology leaks into domain
+order.setForeignKeyCustomerId(customerId);
+order.persist();
+
+// Bad: HTTP concerns leak into domain
+order.deserializeFromJson(request.body);
+order.setHttpStatus(200);
+
+// Good: Domain language only
+order.placeFor(customer);
+orderRepository.save(order);
+```
+
+## Strategic Design Decisions
+
+### When to Split a Bounded Context
+
+Split when:
+- Different parts need to evolve at different speeds
+- Different teams need ownership
+- Model complexity is becoming unmanageable
+- Language conflicts are emerging within the context
+
+Don't split when:
+- Transaction boundaries would become awkward
+- Integration cost outweighs isolation benefit
+- Single team can handle the complexity
+
+### When to Merge Bounded Contexts
+
+Merge when:
+- Integration overhead is excessive
+- Same team owns both
+- Models are converging naturally
+- Separate contexts create artificial complexity
+
+### Dealing with Legacy Systems
+
+1. **Bubble context** - New bounded context with ACL to legacy
+2. **Strangler fig** - Gradually replace legacy feature by feature
+3. **Conformist** - Accept legacy model if acceptable
+4. **Separate ways** - Rebuild independently, migrate data later

.claude/skills/domain-driven-design/references/tactical-patterns.md

@@ -0,0 +1,927 @@
+# Tactical DDD Patterns
+
+Tactical DDD patterns are code-level building blocks for implementing a rich domain model. They help express domain concepts in code that mirrors how domain experts think.
+
+## Entity
+
+### Definition
+
+An object defined by its identity rather than its attributes. Two entities with the same attribute values but different identities are different things.
+
+### Characteristics
+
+- Has a unique identifier that persists through state changes
+- Identity established at creation, immutable thereafter
+- Equality based on identity, not attribute values
+- Has a lifecycle (created, modified, potentially deleted)
+- Contains behavior relevant to the domain concept it represents
+
+### When to Use
+
+- The object represents something tracked over time
+- "Is this the same one?" is a meaningful question
+- The object needs to be referenced from other parts of the system
+- State changes are important to track
+
+### Implementation
+
+```typescript
+// Entity with identity and behavior
+class Order {
+  private readonly _id: OrderId;
+  private _status: OrderStatus;
+  private _items: OrderItem[];
+  private _shippingAddress: Address;
+
+  constructor(id: OrderId, items: OrderItem[], shippingAddress: Address) {
+    this._id = id;
+    this._items = items;
+    this._shippingAddress = shippingAddress;
+    this._status = OrderStatus.Pending;
+  }
+
+  get id(): OrderId {
+    return this._id;
+  }
+
+  // Behavior, not just data access
+  confirm(): void {
+    if (this._items.length === 0) {
+      throw new EmptyOrderError(this._id);
+    }
+    this._status = OrderStatus.Confirmed;
+  }
+
+  ship(trackingNumber: TrackingNumber): void {
+    if (this._status !== OrderStatus.Confirmed) {
+      throw new InvalidOrderStateError(this._id, this._status, 'ship');
+    }
+    this._status = OrderStatus.Shipped;
+    // Domain event raised
+  }
+
+  addItem(item: OrderItem): void {
+    if (this._status !== OrderStatus.Pending) {
+      throw new OrderModificationError(this._id);
+    }
+    this._items.push(item);
+  }
+
+  // Identity-based equality
+  equals(other: Order): boolean {
+    return this._id.equals(other._id);
+  }
+}
+
+// Strongly-typed identity
+class OrderId {
+  constructor(private readonly value: string) {
+    if (!value || value.trim() === '') {
+      throw new InvalidOrderIdError();
+    }
+  }
+
+  equals(other: OrderId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}
+```
+
+### Entity vs Data Structure
+
+```typescript
+// Bad: Anemic entity (data structure)
+class Order {
+  id: string;
+  status: string;
+  items: Item[];
+
+  // Only getters/setters, no behavior
+}
+
+// Good: Rich entity with behavior
+class Order {
+  private _id: OrderId;
+  private _status: OrderStatus;
+  private _items: OrderItem[];
+
+  confirm(): void { /* enforces rules */ }
+  cancel(reason: CancellationReason): void { /* enforces rules */ }
+  addItem(item: OrderItem): void { /* enforces rules */ }
+}
+```
+
+## Value Object
+
+### Definition
+
+An object defined entirely by its attributes. Two value objects with the same attributes are interchangeable. Has no identity.
+
+### Characteristics
+
+- Immutable - once created, never changes
+- Equality based on attributes, not identity
+- Self-validating - always in a valid state
+- Side-effect free - methods return new instances
+- Conceptually whole - attributes form a complete concept
+
+### When to Use
+
+- The concept has no lifecycle or identity
+- "Are these the same?" means "do they have the same values?"
+- Measurement, description, or quantification
+- Combinations of attributes that belong together
+
+### Implementation
+
+```typescript
+// Value Object: Money
+class Money {
+  private constructor(
+    private readonly amount: number,
+    private readonly currency: Currency
+  ) {}
+
+  // Factory method with validation
+  static of(amount: number, currency: Currency): Money {
+    if (amount < 0) {
+      throw new NegativeMoneyError(amount);
+    }
+    return new Money(amount, currency);
+  }
+
+  // Immutable operations - return new instances
+  add(other: Money): Money {
+    this.ensureSameCurrency(other);
+    return Money.of(this.amount + other.amount, this.currency);
+  }
+
+  subtract(other: Money): Money {
+    this.ensureSameCurrency(other);
+    return Money.of(this.amount - other.amount, this.currency);
+  }
+
+  multiply(factor: number): Money {
+    return Money.of(this.amount * factor, this.currency);
+  }
+
+  // Value-based equality
+  equals(other: Money): boolean {
+    return this.amount === other.amount &&
+           this.currency.equals(other.currency);
+  }
+
+  private ensureSameCurrency(other: Money): void {
+    if (!this.currency.equals(other.currency)) {
+      throw new CurrencyMismatchError(this.currency, other.currency);
+    }
+  }
+}
+
+// Value Object: Address
+class Address {
+  private constructor(
+    readonly street: string,
+    readonly city: string,
+    readonly postalCode: string,
+    readonly country: Country
+  ) {}
+
+  static create(street: string, city: string, postalCode: string, country: Country): Address {
+    if (!street || !city || !postalCode) {
+      throw new InvalidAddressError();
+    }
+    if (!country.validatePostalCode(postalCode)) {
+      throw new InvalidPostalCodeError(postalCode, country);
+    }
+    return new Address(street, city, postalCode, country);
+  }
+
+  // Returns new instance with modified value
+  withStreet(newStreet: string): Address {
+    return Address.create(newStreet, this.city, this.postalCode, this.country);
+  }
+
+  equals(other: Address): boolean {
+    return this.street === other.street &&
+           this.city === other.city &&
+           this.postalCode === other.postalCode &&
+           this.country.equals(other.country);
+  }
+}
+
+// Value Object: DateRange
+class DateRange {
+  private constructor(
+    readonly start: Date,
+    readonly end: Date
+  ) {}
+
+  static create(start: Date, end: Date): DateRange {
+    if (end < start) {
+      throw new InvalidDateRangeError(start, end);
+    }
+    return new DateRange(start, end);
+  }
+
+  contains(date: Date): boolean {
+    return date >= this.start && date <= this.end;
+  }
+
+  overlaps(other: DateRange): boolean {
+    return this.start <= other.end && this.end >= other.start;
+  }
+
+  durationInDays(): number {
+    return Math.floor((this.end.getTime() - this.start.getTime()) / (1000 * 60 * 60 * 24));
+  }
+}
+```
+
+### Common Value Objects
+
+| Domain | Value Objects |
+|--------|--------------|
+| **E-commerce** | Money, Price, Quantity, SKU, Address, PhoneNumber |
+| **Healthcare** | BloodPressure, Dosage, DateRange, PatientId |
+| **Finance** | AccountNumber, IBAN, TaxId, Percentage |
+| **Shipping** | Weight, Dimensions, TrackingNumber, PostalCode |
+| **General** | Email, URL, PhoneNumber, Name, Coordinates |
+
+## Aggregate
+
+### Definition
+
+A cluster of entities and value objects with defined boundaries. Has an aggregate root entity that serves as the single entry point. External objects can only reference the root.
+
+### Characteristics
+
+- Defines a transactional consistency boundary
+- Aggregate root is the only externally accessible object
+- Enforces invariants across the cluster
+- Loaded and saved as a unit
+- Other aggregates referenced by identity only
+
+### Design Rules
+
+1. **Protect invariants** - All rules that must be consistent are inside the boundary
+2. **Small aggregates** - Prefer single-entity aggregates; add children only when invariants require
+3. **Reference by identity** - Never hold direct references to other aggregates
+4. **Update one per transaction** - Eventual consistency between aggregates
+5. **Design around invariants** - Identify what must be immediately consistent
+
+### Implementation
+
+```typescript
+// Aggregate: Order (root) with OrderItems (child entities)
+class Order {
+  private readonly _id: OrderId;
+  private _items: Map<ProductId, OrderItem>;
+  private _status: OrderStatus;
+
+  // Invariant: Order total cannot exceed credit limit
+  private _creditLimit: Money;
+
+  private constructor(
+    id: OrderId,
+    creditLimit: Money
+  ) {
+    this._id = id;
+    this._items = new Map();
+    this._status = OrderStatus.Draft;
+    this._creditLimit = creditLimit;
+  }
+
+  static create(id: OrderId, creditLimit: Money): Order {
+    return new Order(id, creditLimit);
+  }
+
+  // All modifications go through aggregate root
+  addItem(productId: ProductId, quantity: Quantity, unitPrice: Money): void {
+    this.ensureCanModify();
+
+    const newItem = OrderItem.create(productId, quantity, unitPrice);
+    const projectedTotal = this.calculateTotalWith(newItem);
+
+    // Invariant enforcement
+    if (projectedTotal.isGreaterThan(this._creditLimit)) {
+      throw new CreditLimitExceededError(projectedTotal, this._creditLimit);
+    }
+
+    this._items.set(productId, newItem);
+  }
+
+  removeItem(productId: ProductId): void {
+    this.ensureCanModify();
+    this._items.delete(productId);
+  }
+
+  updateItemQuantity(productId: ProductId, newQuantity: Quantity): void {
+    this.ensureCanModify();
+
+    const item = this._items.get(productId);
+    if (!item) {
+      throw new ItemNotFoundError(productId);
+    }
+
+    const updatedItem = item.withQuantity(newQuantity);
+    const projectedTotal = this.calculateTotalWithUpdate(productId, updatedItem);
+
+    if (projectedTotal.isGreaterThan(this._creditLimit)) {
+      throw new CreditLimitExceededError(projectedTotal, this._creditLimit);
+    }
+
+    this._items.set(productId, updatedItem);
+  }
+
+  submit(): OrderSubmitted {
+    if (this._items.size === 0) {
+      throw new EmptyOrderError();
+    }
+    this._status = OrderStatus.Submitted;
+
+    return new OrderSubmitted(this._id, this.total(), new Date());
+  }
+
+  // Read-only access to child entities
+  get items(): ReadonlyArray<OrderItem> {
+    return Array.from(this._items.values());
+  }
+
+  total(): Money {
+    return this.items.reduce(
+      (sum, item) => sum.add(item.subtotal()),
+      Money.zero(Currency.USD)
+    );
+  }
+
+  private ensureCanModify(): void {
+    if (this._status !== OrderStatus.Draft) {
+      throw new OrderNotModifiableError(this._id, this._status);
+    }
+  }
+
+  private calculateTotalWith(newItem: OrderItem): Money {
+    return this.total().add(newItem.subtotal());
+  }
+
+  private calculateTotalWithUpdate(productId: ProductId, updatedItem: OrderItem): Money {
+    const currentItem = this._items.get(productId)!;
+    return this.total().subtract(currentItem.subtotal()).add(updatedItem.subtotal());
+  }
+}
+
+// Child entity - only accessible through aggregate root
+class OrderItem {
+  private constructor(
+    private readonly _productId: ProductId,
+    private _quantity: Quantity,
+    private readonly _unitPrice: Money
+  ) {}
+
+  static create(productId: ProductId, quantity: Quantity, unitPrice: Money): OrderItem {
+    return new OrderItem(productId, quantity, unitPrice);
+  }
+
+  get productId(): ProductId { return this._productId; }
+  get quantity(): Quantity { return this._quantity; }
+  get unitPrice(): Money { return this._unitPrice; }
+
+  subtotal(): Money {
+    return this._unitPrice.multiply(this._quantity.value);
+  }
+
+  withQuantity(newQuantity: Quantity): OrderItem {
+    return new OrderItem(this._productId, newQuantity, this._unitPrice);
+  }
+}
+```
+
+### Aggregate Reference Patterns
+
+```typescript
+// Bad: Direct object reference across aggregates
+class Order {
+  private customer: Customer;  // Holds the entire aggregate!
+}
+
+// Good: Reference by identity
+class Order {
+  private customerId: CustomerId;
+
+  // If customer data needed, load separately
+  getCustomerAddress(customerRepository: CustomerRepository): Address {
+    const customer = customerRepository.findById(this.customerId);
+    return customer.shippingAddress;
+  }
+}
+```
+
+## Domain Event
+
+### Definition
+
+A record of something significant that happened in the domain. Captures state changes that domain experts care about.
+
+### Characteristics
+
+- Named in past tense (OrderPlaced, PaymentReceived)
+- Immutable - records historical fact
+- Contains all relevant data about what happened
+- Published after state change is committed
+- May trigger reactions in same or different bounded contexts
+
+### When to Use
+
+- Domain experts talk about "when X happens, Y should happen"
+- Need to communicate changes across aggregate boundaries
+- Maintaining an audit trail
+- Implementing eventual consistency
+- Integration with other bounded contexts
+
+### Implementation
+
+```typescript
+// Base domain event
+abstract class DomainEvent {
+  readonly occurredAt: Date;
+  readonly eventId: string;
+
+  constructor() {
+    this.occurredAt = new Date();
+    this.eventId = generateUUID();
+  }
+
+  abstract get eventType(): string;
+}
+
+// Specific domain events
+class OrderPlaced extends DomainEvent {
+  constructor(
+    readonly orderId: OrderId,
+    readonly customerId: CustomerId,
+    readonly totalAmount: Money,
+    readonly items: ReadonlyArray<OrderItemSnapshot>
+  ) {
+    super();
+  }
+
+  get eventType(): string {
+    return 'order.placed';
+  }
+}
+
+class OrderShipped extends DomainEvent {
+  constructor(
+    readonly orderId: OrderId,
+    readonly trackingNumber: TrackingNumber,
+    readonly carrier: string,
+    readonly estimatedDelivery: Date
+  ) {
+    super();
+  }
+
+  get eventType(): string {
+    return 'order.shipped';
+  }
+}
+
+class PaymentReceived extends DomainEvent {
+  constructor(
+    readonly orderId: OrderId,
+    readonly amount: Money,
+    readonly paymentMethod: PaymentMethod,
+    readonly transactionId: string
+  ) {
+    super();
+  }
+
+  get eventType(): string {
+    return 'payment.received';
+  }
+}
+
+// Entity raising events
+class Order {
+  private _domainEvents: DomainEvent[] = [];
+
+  submit(): void {
+    // State change
+    this._status = OrderStatus.Submitted;
+
+    // Raise event
+    this._domainEvents.push(
+      new OrderPlaced(
+        this._id,
+        this._customerId,
+        this.total(),
+        this.itemSnapshots()
+      )
+    );
+  }
+
+  pullDomainEvents(): DomainEvent[] {
+    const events = [...this._domainEvents];
+    this._domainEvents = [];
+    return events;
+  }
+}
+
+// Event handler
+class OrderPlacedHandler {
+  constructor(
+    private inventoryService: InventoryService,
+    private emailService: EmailService
+  ) {}
+
+  async handle(event: OrderPlaced): Promise<void> {
+    // Reserve inventory (different aggregate)
+    await this.inventoryService.reserveItems(event.items);
+
+    // Send confirmation email
+    await this.emailService.sendOrderConfirmation(
+      event.customerId,
+      event.orderId,
+      event.totalAmount
+    );
+  }
+}
+```
+
+### Event Publishing Patterns
+
+```typescript
+// Pattern 1: Collect and dispatch after save
+class OrderApplicationService {
+  async placeOrder(command: PlaceOrderCommand): Promise<OrderId> {
+    const order = Order.create(command);
+
+    await this.orderRepository.save(order);
+
+    // Dispatch events after successful save
+    const events = order.pullDomainEvents();
+    await this.eventDispatcher.dispatchAll(events);
+
+    return order.id;
+  }
+}
+
+// Pattern 2: Outbox pattern (reliable publishing)
+class OrderApplicationService {
+  async placeOrder(command: PlaceOrderCommand): Promise<OrderId> {
+    await this.unitOfWork.transaction(async () => {
+      const order = Order.create(command);
+      await this.orderRepository.save(order);
+
+      // Save events to outbox in same transaction
+      const events = order.pullDomainEvents();
+      await this.outbox.saveEvents(events);
+    });
+
+    // Separate process publishes from outbox
+    return order.id;
+  }
+}
+```
+
+## Repository
+
+### Definition
+
+Mediates between the domain and data mapping layers. Provides collection-like interface for accessing aggregates.
+
+### Characteristics
+
+- One repository per aggregate root
+- Interface defined in domain layer, implementation in infrastructure
+- Returns fully reconstituted aggregates
+- Abstracts persistence concerns from domain
+
+### Interface Design
+
+```typescript
+// Domain layer interface
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>;
+  save(order: Order): Promise<void>;
+  delete(order: Order): Promise<void>;
+
+  // Domain-specific queries
+  findPendingOrdersFor(customerId: CustomerId): Promise<Order[]>;
+  findOrdersToShipBefore(deadline: Date): Promise<Order[]>;
+}
+
+// Infrastructure implementation
+class PostgresOrderRepository implements OrderRepository {
+  constructor(private db: Database) {}
+
+  async findById(id: OrderId): Promise<Order | null> {
+    const row = await this.db.query(
+      'SELECT * FROM orders WHERE id = $1',
+      [id.toString()]
+    );
+
+    if (!row) return null;
+
+    const items = await this.db.query(
+      'SELECT * FROM order_items WHERE order_id = $1',
+      [id.toString()]
+    );
+
+    return this.reconstitute(row, items);
+  }
+
+  async save(order: Order): Promise<void> {
+    await this.db.transaction(async (tx) => {
+      await tx.query(
+        'INSERT INTO orders (id, status, customer_id) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET status = $2',
+        [order.id.toString(), order.status, order.customerId.toString()]
+      );
+
+      // Save items
+      for (const item of order.items) {
+        await tx.query(
+          'INSERT INTO order_items (order_id, product_id, quantity, unit_price) VALUES ($1, $2, $3, $4) ON CONFLICT DO UPDATE...',
+          [order.id.toString(), item.productId.toString(), item.quantity.value, item.unitPrice.amount]
+        );
+      }
+    });
+  }
+
+  private reconstitute(orderRow: any, itemRows: any[]): Order {
+    // Rebuild aggregate from persistence data
+    return Order.reconstitute({
+      id: OrderId.from(orderRow.id),
+      status: OrderStatus[orderRow.status],
+      customerId: CustomerId.from(orderRow.customer_id),
+      items: itemRows.map(row => OrderItem.reconstitute({
+        productId: ProductId.from(row.product_id),
+        quantity: Quantity.of(row.quantity),
+        unitPrice: Money.of(row.unit_price, Currency.USD)
+      }))
+    });
+  }
+}
+```
+
+### Repository vs DAO
+
+```typescript
+// DAO: Data-centric, returns raw data
+interface OrderDao {
+  findById(id: string): Promise<OrderRow>;
+  findItems(orderId: string): Promise<OrderItemRow[]>;
+  insert(row: OrderRow): Promise<void>;
+}
+
+// Repository: Domain-centric, returns aggregates
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>;
+  save(order: Order): Promise<void>;
+}
+```
+
+## Domain Service
+
+### Definition
+
+Stateless operations that represent domain concepts but don't naturally belong to any entity or value object.
+
+### When to Use
+
+- The operation involves multiple aggregates
+- The operation represents a domain concept
+- Putting the operation on an entity would create awkward dependencies
+- The operation is stateless
+
+### Examples
+
+```typescript
+// Domain Service: Transfer money between accounts
+class MoneyTransferService {
+  transfer(
+    from: Account,
+    to: Account,
+    amount: Money
+  ): TransferResult {
+    // Involves two aggregates
+    // Neither account should "own" this operation
+
+    if (!from.canWithdraw(amount)) {
+      return TransferResult.insufficientFunds();
+    }
+
+    from.withdraw(amount);
+    to.deposit(amount);
+
+    return TransferResult.success(
+      new MoneyTransferred(from.id, to.id, amount)
+    );
+  }
+}
+
+// Domain Service: Calculate shipping cost
+class ShippingCostCalculator {
+  constructor(
+    private rateProvider: ShippingRateProvider
+  ) {}
+
+  calculate(
+    items: OrderItem[],
+    destination: Address,
+    shippingMethod: ShippingMethod
+  ): Money {
+    const totalWeight = items.reduce(
+      (sum, item) => sum.add(item.weight),
+      Weight.zero()
+    );
+
+    const rate = this.rateProvider.getRate(
+      destination.country,
+      shippingMethod
+    );
+
+    return rate.calculateFor(totalWeight);
+  }
+}
+
+// Domain Service: Check inventory availability
+class InventoryAvailabilityService {
+  constructor(
+    private inventoryRepository: InventoryRepository
+  ) {}
+
+  checkAvailability(
+    items: Array<{ productId: ProductId; quantity: Quantity }>
+  ): AvailabilityResult {
+    const unavailable: ProductId[] = [];
+
+    for (const { productId, quantity } of items) {
+      const inventory = this.inventoryRepository.findByProductId(productId);
+      if (!inventory || !inventory.hasAvailable(quantity)) {
+        unavailable.push(productId);
+      }
+    }
+
+    return unavailable.length === 0
+      ? AvailabilityResult.allAvailable()
+      : AvailabilityResult.someUnavailable(unavailable);
+  }
+}
+```
+
+### Domain Service vs Application Service
+
+```typescript
+// Domain Service: Domain logic, domain types, stateless
+class PricingService {
+  calculateDiscountedPrice(product: Product, customer: Customer): Money {
+    const basePrice = product.price;
+    const discount = customer.membershipLevel.discountPercentage;
+    return basePrice.applyDiscount(discount);
+  }
+}
+
+// Application Service: Orchestration, use cases, transaction boundary
+class OrderApplicationService {
+  constructor(
+    private orderRepository: OrderRepository,
+    private pricingService: PricingService,
+    private eventPublisher: EventPublisher
+  ) {}
+
+  async createOrder(command: CreateOrderCommand): Promise<OrderId> {
+    const customer = await this.customerRepository.findById(command.customerId);
+    const order = Order.create(command.orderId, customer.id);
+
+    for (const item of command.items) {
+      const product = await this.productRepository.findById(item.productId);
+      const price = this.pricingService.calculateDiscountedPrice(product, customer);
+      order.addItem(item.productId, item.quantity, price);
+    }
+
+    await this.orderRepository.save(order);
+    await this.eventPublisher.publish(order.pullDomainEvents());
+
+    return order.id;
+  }
+}
+```
+
+## Factory
+
+### Definition
+
+Encapsulates complex object or aggregate creation logic. Creates objects in a valid state.
+
+### When to Use
+
+- Construction logic is complex
+- Multiple ways to create the same type of object
+- Creation involves other objects or services
+- Need to enforce invariants at creation time
+
+### Implementation
+
+```typescript
+// Factory as static method
+class Order {
+  static create(customerId: CustomerId, creditLimit: Money): Order {
+    return new Order(
+      OrderId.generate(),
+      customerId,
+      creditLimit,
+      OrderStatus.Draft,
+      []
+    );
+  }
+
+  static reconstitute(data: OrderData): Order {
+    // For rebuilding from persistence
+    return new Order(
+      data.id,
+      data.customerId,
+      data.creditLimit,
+      data.status,
+      data.items
+    );
+  }
+}
+
+// Factory as separate class
+class OrderFactory {
+  constructor(
+    private creditLimitService: CreditLimitService,
+    private idGenerator: IdGenerator
+  ) {}
+
+  async createForCustomer(customerId: CustomerId): Promise<Order> {
+    const creditLimit = await this.creditLimitService.getLimit(customerId);
+    const orderId = this.idGenerator.generate();
+
+    return Order.create(orderId, customerId, creditLimit);
+  }
+
+  createFromQuote(quote: Quote): Order {
+    const order = Order.create(
+      this.idGenerator.generate(),
+      quote.customerId,
+      quote.creditLimit
+    );
+
+    for (const item of quote.items) {
+      order.addItem(item.productId, item.quantity, item.agreedPrice);
+    }
+
+    return order;
+  }
+}
+
+// Builder pattern for complex construction
+class OrderBuilder {
+  private customerId?: CustomerId;
+  private items: OrderItemData[] = [];
+  private shippingAddress?: Address;
+  private billingAddress?: Address;
+
+  forCustomer(customerId: CustomerId): this {
+    this.customerId = customerId;
+    return this;
+  }
+
+  withItem(productId: ProductId, quantity: Quantity, price: Money): this {
+    this.items.push({ productId, quantity, price });
+    return this;
+  }
+
+  shippingTo(address: Address): this {
+    this.shippingAddress = address;
+    return this;
+  }
+
+  billingTo(address: Address): this {
+    this.billingAddress = address;
+    return this;
+  }
+
+  build(): Order {
+    if (!this.customerId) throw new Error('Customer required');
+    if (!this.shippingAddress) throw new Error('Shipping address required');
+    if (this.items.length === 0) throw new Error('At least one item required');
+
+    const order = Order.create(this.customerId);
+    order.setShippingAddress(this.shippingAddress);
+    order.setBillingAddress(this.billingAddress ?? this.shippingAddress);
+
+    for (const item of this.items) {
+      order.addItem(item.productId, item.quantity, item.price);
+    }
+
+    return order;
+  }
+}
+```

.claude/skills/elliptic-curves/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: elliptic-curves
+description: This skill should be used when working with elliptic curve cryptography, implementing or debugging secp256k1 operations, understanding modular arithmetic and finite fields, or implementing signature schemes like ECDSA and Schnorr. Provides comprehensive knowledge of group theory foundations, curve mathematics, point multiplication algorithms, and cryptographic optimizations.
+---
+
+# Elliptic Curve Cryptography
+
+This skill provides deep knowledge of elliptic curve cryptography (ECC), with particular focus on the secp256k1 curve used in Bitcoin and Nostr, including the mathematical foundations and implementation considerations.
+
+## When to Use This Skill
+
+- Implementing or debugging elliptic curve operations
+- Working with secp256k1, ECDSA, or Schnorr signatures
+- Understanding modular arithmetic and finite field operations
+- Optimizing cryptographic code for performance
+- Analyzing security properties of curve-based cryptography
+
+## Mathematical Foundations
+
+### Groups in Cryptography
+
+A **group** is a set G with a binary operation (often denoted · or +) satisfying:
+
+1. **Closure**: For all a, b ∈ G, the result a · b is also in G
+2. **Associativity**: (a · b) · c = a · (b · c)
+3. **Identity**: There exists e ∈ G such that e · a = a · e = a
+4. **Inverse**: For each a ∈ G, there exists a⁻¹ such that a · a⁻¹ = e
+
+A **cyclic group** is generated by repeatedly applying the operation to a single element (the generator). The **order** of a group is the number of elements.
+
+**Why groups matter in cryptography**: The discrete logarithm problem—given g and gⁿ, find n—is computationally hard in certain groups, forming the security basis for ECC.
+
+### Modular Arithmetic
+
+Modular arithmetic constrains calculations to a finite range [0, p-1] for some modulus p:
+
+```
+a ≡ b (mod p)  means  p divides (a - b)
+
+Operations:
+- Addition:       (a + b) mod p
+- Subtraction:    (a - b + p) mod p
+- Multiplication: (a × b) mod p
+- Inverse:        a⁻¹ where (a × a⁻¹) ≡ 1 (mod p)
+```
+
+**Computing modular inverse**:
+- **Fermat's Little Theorem**: If p is prime, a⁻¹ ≡ a^(p-2) (mod p)
+- **Extended Euclidean Algorithm**: More efficient for general cases
+- **SafeGCD Algorithm**: Constant-time, used in libsecp256k1
+
+### Finite Fields (Galois Fields)
+
+A **finite field** GF(p) or 𝔽ₚ is a field with a finite number of elements where:
+- p must be prime (or a prime power for extension fields)
+- All arithmetic operations are defined and produce elements within the field
+- Every non-zero element has a multiplicative inverse
+
+For cryptographic curves like secp256k1, the field is 𝔽ₚ where p is a 256-bit prime.
+
+**Key property**: The non-zero elements of a finite field form a cyclic group under multiplication.
+
+## Elliptic Curves
+
+### The Curve Equation
+
+An elliptic curve over a finite field 𝔽ₚ is defined by the Weierstrass equation:
+
+```
+y² = x³ + ax + b  (mod p)
+```
+
+The curve must satisfy the non-singularity condition: 4a³ + 27b² ≠ 0
+
+### Points on the Curve
+
+A point P = (x, y) is on the curve if it satisfies the equation. The set of all points, plus a special "point at infinity" O (the identity element), forms an abelian group.
+
+### Point Operations
+
+**Point Addition (P + Q where P ≠ Q)**:
+```
+λ = (y₂ - y₁) / (x₂ - x₁)  (mod p)
+x₃ = λ² - x₁ - x₂          (mod p)
+y₃ = λ(x₁ - x₃) - y₁       (mod p)
+```
+
+**Point Doubling (P + P = 2P)**:
+```
+λ = (3x₁² + a) / (2y₁)     (mod p)
+x₃ = λ² - 2x₁              (mod p)
+y₃ = λ(x₁ - x₃) - y₁       (mod p)
+```
+
+**Point at Infinity**: Acts as the identity element; P + O = P for all P.
+
+**Point Negation**: -P = (x, -y) = (x, p - y)
+
+## The secp256k1 Curve
+
+### Parameters
+
+secp256k1 is defined by SECG (Standards for Efficient Cryptography Group):
+
+```
+Curve equation: y² = x³ + 7  (a = 0, b = 7)
+
+Prime modulus p:
+  0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F
+  = 2²⁵⁶ - 2³² - 977
+
+Group order n:
+  0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364141
+
+Generator point G:
+  Gx = 0x79BE667E F9DCBBAC 55A06295 CE870B07 029BFCDB 2DCE28D9 59F2815B 16F81798
+  Gy = 0x483ADA77 26A3C465 5DA4FBFC 0E1108A8 FD17B448 A6855419 9C47D08F FB10D4B8
+
+Cofactor h = 1
+```
+
+### Why secp256k1?
+
+1. **Koblitz curve**: a = 0 enables faster computation (no ax term)
+2. **Special prime**: p = 2²⁵⁶ - 2³² - 977 allows efficient modular reduction
+3. **Deterministic construction**: Not randomly generated, reducing backdoor concerns
+4. **~30% faster** than random curves when fully optimized
+
+### Efficient Modular Reduction
+
+The special form of p enables fast reduction without general division:
+
+```
+For p = 2²⁵⁶ - 2³² - 977:
+To reduce a 512-bit number c = c_high × 2²⁵⁶ + c_low:
+  c ≡ c_low + c_high × 2³² + c_high × 977 (mod p)
+```
+
+## Point Multiplication Algorithms
+
+Scalar multiplication kP (computing P + P + ... + P, k times) is the core operation.
+
+### Double-and-Add (Binary Method)
+
+```
+Input: k (scalar), P (point)
+Output: kP
+
+R = O (point at infinity)
+for i from bit_length(k)-1 down to 0:
+    R = 2R           # Point doubling
+    if bit i of k is 1:
+        R = R + P    # Point addition
+return R
+```
+
+**Complexity**: O(log k) point operations
+**Vulnerability**: Timing side-channels (different branches for 0/1 bits)
+
+### Montgomery Ladder
+
+Constant-time algorithm that performs the same operations regardless of bit values:
+
+```
+Input: k (scalar), P (point)
+Output: kP
+
+R0 = O
+R1 = P
+for i from bit_length(k)-1 down to 0:
+    if bit i of k is 0:
+        R1 = R0 + R1
+        R0 = 2R0
+    else:
+        R0 = R0 + R1
+        R1 = 2R1
+return R0
+```
+
+**Advantage**: Resistant to simple power analysis and timing attacks.
+
+### Window Methods (w-NAF)
+
+Precompute small multiples of P, then process w bits at a time:
+
+```
+w-NAF representation reduces additions by ~1/3 compared to binary
+Precomputation table: [P, 3P, 5P, 7P, ...] for w=4
+```
+
+### Endomorphism Optimization (GLV Method)
+
+secp256k1 has an efficiently computable endomorphism φ where:
+```
+φ(x, y) = (βx, y)  where β³ ≡ 1 (mod p)
+φ(P) = λP          where λ³ ≡ 1 (mod n)
+```
+
+This allows splitting scalar k into k₁ + k₂λ with smaller k₁, k₂, reducing operations by ~33-50%.
+
+### Multi-Scalar Multiplication (Strauss-Shamir)
+
+For computing k₁P₁ + k₂P₂ (common in signature verification):
+
+```
+Process both scalars simultaneously, combining operations
+Reduces work compared to separate multiplications
+```
+
+## Coordinate Systems
+
+### Affine Coordinates
+
+Standard (x, y) representation. Requires modular inversion for each operation.
+
+### Projective Coordinates
+
+Represent (X:Y:Z) where x = X/Z, y = Y/Z:
+- Avoids inversions during intermediate computations
+- Only one inversion at the end to convert back to affine
+
+### Jacobian Coordinates
+
+Represent (X:Y:Z) where x = X/Z², y = Y/Z³:
+- Fastest for point doubling
+- Used extensively in libsecp256k1
+
+### López-Dahab Coordinates
+
+For curves over GF(2ⁿ), optimized for binary field arithmetic.
+
+## Signature Schemes
+
+### ECDSA (Elliptic Curve Digital Signature Algorithm)
+
+**Key Generation**:
+```
+Private key: d (random integer in [1, n-1])
+Public key: Q = dG
+```
+
+**Signing message m**:
+```
+1. Hash: e = H(m) truncated to curve order bit length
+2. Random: k ∈ [1, n-1]
+3. Compute: (x, y) = kG
+4. Calculate: r = x mod n  (if r = 0, restart with new k)
+5. Calculate: s = k⁻¹(e + rd) mod n  (if s = 0, restart)
+6. Signature: (r, s)
+```
+
+**Verification of signature (r, s) on message m**:
+```
+1. Check: r, s ∈ [1, n-1]
+2. Hash: e = H(m)
+3. Compute: w = s⁻¹ mod n
+4. Compute: u₁ = ew mod n, u₂ = rw mod n
+5. Compute: (x, y) = u₁G + u₂Q
+6. Valid if: r ≡ x (mod n)
+```
+
+**Security considerations**:
+- k MUST be unique per signature (reuse leaks private key)
+- Use RFC 6979 for deterministic k derivation
+
+### Schnorr Signatures (BIP-340)
+
+Simpler, more efficient, with provable security.
+
+**Signing message m**:
+```
+1. Random: k ∈ [1, n-1]
+2. Compute: R = kG
+3. Challenge: e = H(R || Q || m)
+4. Response: s = k + ed mod n
+5. Signature: (R, s) or (r_x, s) where r_x is x-coordinate of R
+```
+
+**Verification**:
+```
+1. Compute: e = H(R || Q || m)
+2. Check: sG = R + eQ
+```
+
+**Advantages over ECDSA**:
+- Linear: enables signature aggregation (MuSig)
+- Simpler verification (no modular inverse)
+- Batch verification support
+- Provably secure in Random Oracle Model
+
+## Implementation Considerations
+
+### Constant-Time Operations
+
+To prevent timing attacks:
+- Avoid branches dependent on secret data
+- Use constant-time comparison functions
+- Mask operations to hide data-dependent timing
+
+```go
+// BAD: Timing leak
+if secretBit == 1 {
+    doOperation()
+}
+
+// GOOD: Constant-time conditional
+result = conditionalSelect(secretBit, value1, value0)
+```
+
+### Memory Safety
+
+- Zeroize sensitive data after use
+- Avoid leaving secrets in registers or cache
+- Use secure memory allocation when available
+
+### Side-Channel Protections
+
+- **Timing attacks**: Use constant-time algorithms
+- **Power analysis**: Montgomery ladder, point blinding
+- **Cache attacks**: Avoid table lookups indexed by secrets
+
+### Random Number Generation
+
+- Use cryptographically secure RNG for k in ECDSA
+- Consider deterministic k (RFC 6979) for reproducibility
+- Validate output is in valid range [1, n-1]
+
+## libsecp256k1 Optimizations
+
+The Bitcoin Core library includes:
+
+1. **Field arithmetic**: 5×52-bit limbs for 64-bit platforms
+2. **Scalar arithmetic**: 4×64-bit representation
+3. **Endomorphism**: GLV decomposition enabled by default
+4. **Batch inversion**: Amortizes expensive inversions
+5. **SafeGCD**: Constant-time modular inverse
+6. **Precomputed tables**: For generator point multiplications
+
+## Security Properties
+
+### Discrete Logarithm Problem (DLP)
+
+Given P and Q = kP, finding k is computationally infeasible.
+
+**Best known attacks**:
+- Generic: Baby-step Giant-step, Pollard's rho: O(√n) operations
+- For secp256k1: ~2¹²⁸ operations (128-bit security)
+
+### Curve Security Criteria
+
+- Large prime order subgroup
+- Cofactor 1 (no small subgroup attacks)
+- Resistant to MOV attack (embedding degree)
+- Not anomalous (n ≠ p)
+
+## Common Pitfalls
+
+1. **k reuse in ECDSA**: Immediately leaks private key
+2. **Weak random k**: Partially leaks key over multiple signatures
+3. **Invalid curve points**: Validate points are on curve
+4. **Small subgroup attacks**: Check point order (cofactor = 1 helps)
+5. **Timing leaks**: Non-constant-time scalar multiplication
+
+## References
+
+For detailed implementations, see:
+- `references/secp256k1-parameters.md` - Full curve parameters
+- `references/algorithms.md` - Detailed algorithm pseudocode
+- `references/security.md` - Security analysis and attack vectors

.claude/skills/elliptic-curves/references/algorithms.md

@@ -0,0 +1,513 @@
+# Elliptic Curve Algorithms
+
+Detailed pseudocode for core elliptic curve operations.
+
+## Field Arithmetic
+
+### Modular Addition
+
+```
+function mod_add(a, b, p):
+    result = a + b
+    if result >= p:
+        result = result - p
+    return result
+```
+
+### Modular Subtraction
+
+```
+function mod_sub(a, b, p):
+    if a >= b:
+        return a - b
+    else:
+        return p - b + a
+```
+
+### Modular Multiplication
+
+For general case:
+```
+function mod_mul(a, b, p):
+    return (a * b) mod p
+```
+
+For secp256k1 optimized (Barrett reduction):
+```
+function mod_mul_secp256k1(a, b):
+    # Compute full 512-bit product
+    product = a * b
+
+    # Split into high and low 256-bit parts
+    low = product & ((1 << 256) - 1)
+    high = product >> 256
+
+    # Reduce: result ≡ low + high * (2³² + 977) (mod p)
+    result = low + high * (1 << 32) + high * 977
+
+    # May need additional reduction
+    while result >= p:
+        result = result - p
+
+    return result
+```
+
+### Modular Inverse
+
+**Extended Euclidean Algorithm**:
+```
+function mod_inverse(a, p):
+    if a == 0:
+        error "No inverse exists for 0"
+
+    old_r, r = p, a
+    old_s, s = 0, 1
+
+    while r != 0:
+        quotient = old_r / r
+        old_r, r = r, old_r - quotient * r
+        old_s, s = s, old_s - quotient * s
+
+    if old_r != 1:
+        error "No inverse exists"
+
+    if old_s < 0:
+        old_s = old_s + p
+
+    return old_s
+```
+
+**Fermat's Little Theorem** (for prime p):
+```
+function mod_inverse_fermat(a, p):
+    return mod_exp(a, p - 2, p)
+```
+
+### Modular Exponentiation (Square-and-Multiply)
+
+```
+function mod_exp(base, exp, p):
+    result = 1
+    base = base mod p
+
+    while exp > 0:
+        if exp & 1:  # exp is odd
+            result = (result * base) mod p
+        exp = exp >> 1
+        base = (base * base) mod p
+
+    return result
+```
+
+### Modular Square Root (Tonelli-Shanks)
+
+For secp256k1 where p ≡ 3 (mod 4):
+```
+function mod_sqrt(a, p):
+    # For p ≡ 3 (mod 4), sqrt(a) = a^((p+1)/4)
+    return mod_exp(a, (p + 1) / 4, p)
+```
+
+## Point Operations
+
+### Point Validation
+
+```
+function is_on_curve(P, a, b, p):
+    if P is infinity:
+        return true
+
+    x, y = P
+    left = (y * y) mod p
+    right = (x * x * x + a * x + b) mod p
+
+    return left == right
+```
+
+### Point Addition (Affine Coordinates)
+
+```
+function point_add(P, Q, a, p):
+    if P is infinity:
+        return Q
+    if Q is infinity:
+        return P
+
+    x1, y1 = P
+    x2, y2 = Q
+
+    if x1 == x2:
+        if y1 == mod_neg(y2, p):  # P = -Q
+            return infinity
+        else:  # P == Q
+            return point_double(P, a, p)
+
+    # λ = (y2 - y1) / (x2 - x1)
+    numerator = mod_sub(y2, y1, p)
+    denominator = mod_sub(x2, x1, p)
+    λ = mod_mul(numerator, mod_inverse(denominator, p), p)
+
+    # x3 = λ² - x1 - x2
+    x3 = mod_sub(mod_sub(mod_mul(λ, λ, p), x1, p), x2, p)
+
+    # y3 = λ(x1 - x3) - y1
+    y3 = mod_sub(mod_mul(λ, mod_sub(x1, x3, p), p), y1, p)
+
+    return (x3, y3)
+```
+
+### Point Doubling (Affine Coordinates)
+
+```
+function point_double(P, a, p):
+    if P is infinity:
+        return infinity
+
+    x, y = P
+
+    if y == 0:
+        return infinity
+
+    # λ = (3x² + a) / (2y)
+    numerator = mod_add(mod_mul(3, mod_mul(x, x, p), p), a, p)
+    denominator = mod_mul(2, y, p)
+    λ = mod_mul(numerator, mod_inverse(denominator, p), p)
+
+    # x3 = λ² - 2x
+    x3 = mod_sub(mod_mul(λ, λ, p), mod_mul(2, x, p), p)
+
+    # y3 = λ(x - x3) - y
+    y3 = mod_sub(mod_mul(λ, mod_sub(x, x3, p), p), y, p)
+
+    return (x3, y3)
+```
+
+### Point Negation
+
+```
+function point_negate(P, p):
+    if P is infinity:
+        return infinity
+
+    x, y = P
+    return (x, p - y)
+```
+
+## Scalar Multiplication
+
+### Double-and-Add (Left-to-Right)
+
+```
+function scalar_mult_double_add(k, P, a, p):
+    if k == 0 or P is infinity:
+        return infinity
+
+    if k < 0:
+        k = -k
+        P = point_negate(P, p)
+
+    R = infinity
+    bits = binary_representation(k)  # MSB first
+
+    for bit in bits:
+        R = point_double(R, a, p)
+        if bit == 1:
+            R = point_add(R, P, a, p)
+
+    return R
+```
+
+### Montgomery Ladder (Constant-Time)
+
+```
+function scalar_mult_montgomery(k, P, a, p):
+    R0 = infinity
+    R1 = P
+
+    bits = binary_representation(k)  # MSB first
+
+    for bit in bits:
+        if bit == 0:
+            R1 = point_add(R0, R1, a, p)
+            R0 = point_double(R0, a, p)
+        else:
+            R0 = point_add(R0, R1, a, p)
+            R1 = point_double(R1, a, p)
+
+    return R0
+```
+
+### w-NAF Scalar Multiplication
+
+```
+function compute_wNAF(k, w):
+    # Convert scalar to width-w Non-Adjacent Form
+    naf = []
+
+    while k > 0:
+        if k & 1:  # k is odd
+            # Get w-bit window
+            digit = k mod (1 << w)
+            if digit >= (1 << (w-1)):
+                digit = digit - (1 << w)
+            naf.append(digit)
+            k = k - digit
+        else:
+            naf.append(0)
+        k = k >> 1
+
+    return naf
+
+function scalar_mult_wNAF(k, P, w, a, p):
+    # Precompute odd multiples: [P, 3P, 5P, ..., (2^(w-1)-1)P]
+    precomp = [P]
+    P2 = point_double(P, a, p)
+    for i in range(1, 1 << (w-1)):
+        precomp.append(point_add(precomp[-1], P2, a, p))
+
+    # Convert k to w-NAF
+    naf = compute_wNAF(k, w)
+
+    # Compute scalar multiplication
+    R = infinity
+    for i in range(len(naf) - 1, -1, -1):
+        R = point_double(R, a, p)
+        digit = naf[i]
+        if digit > 0:
+            R = point_add(R, precomp[(digit - 1) / 2], a, p)
+        elif digit < 0:
+            R = point_add(R, point_negate(precomp[(-digit - 1) / 2], p), a, p)
+
+    return R
+```
+
+### Shamir's Trick (Multi-Scalar)
+
+For computing k₁P + k₂Q efficiently:
+
+```
+function multi_scalar_mult(k1, P, k2, Q, a, p):
+    # Precompute P + Q
+    PQ = point_add(P, Q, a, p)
+
+    # Get binary representations (same length, padded)
+    bits1 = binary_representation(k1)
+    bits2 = binary_representation(k2)
+    max_len = max(len(bits1), len(bits2))
+    bits1 = pad_left(bits1, max_len)
+    bits2 = pad_left(bits2, max_len)
+
+    R = infinity
+
+    for i in range(max_len):
+        R = point_double(R, a, p)
+
+        b1, b2 = bits1[i], bits2[i]
+
+        if b1 == 1 and b2 == 1:
+            R = point_add(R, PQ, a, p)
+        elif b1 == 1:
+            R = point_add(R, P, a, p)
+        elif b2 == 1:
+            R = point_add(R, Q, a, p)
+
+    return R
+```
+
+## Jacobian Coordinates
+
+More efficient for repeated operations.
+
+### Conversion
+
+```
+# Affine to Jacobian
+function affine_to_jacobian(P):
+    if P is infinity:
+        return (1, 1, 0)  # Jacobian infinity
+    x, y = P
+    return (x, y, 1)
+
+# Jacobian to Affine
+function jacobian_to_affine(P, p):
+    X, Y, Z = P
+    if Z == 0:
+        return infinity
+
+    Z_inv = mod_inverse(Z, p)
+    Z_inv2 = mod_mul(Z_inv, Z_inv, p)
+    Z_inv3 = mod_mul(Z_inv2, Z_inv, p)
+
+    x = mod_mul(X, Z_inv2, p)
+    y = mod_mul(Y, Z_inv3, p)
+
+    return (x, y)
+```
+
+### Point Doubling (Jacobian)
+
+For curve y² = x³ + 7 (a = 0):
+
+```
+function jacobian_double(P, p):
+    X, Y, Z = P
+
+    if Y == 0:
+        return (1, 1, 0)  # infinity
+
+    # For a = 0: M = 3*X²
+    S = mod_mul(4, mod_mul(X, mod_mul(Y, Y, p), p), p)
+    M = mod_mul(3, mod_mul(X, X, p), p)
+
+    X3 = mod_sub(mod_mul(M, M, p), mod_mul(2, S, p), p)
+    Y3 = mod_sub(mod_mul(M, mod_sub(S, X3, p), p),
+                  mod_mul(8, mod_mul(Y, Y, mod_mul(Y, Y, p), p), p), p)
+    Z3 = mod_mul(2, mod_mul(Y, Z, p), p)
+
+    return (X3, Y3, Z3)
+```
+
+### Point Addition (Jacobian + Affine)
+
+Mixed addition is faster when one point is in affine:
+
+```
+function jacobian_add_affine(P, Q, p):
+    # P in Jacobian (X1, Y1, Z1), Q in affine (x2, y2)
+    X1, Y1, Z1 = P
+    x2, y2 = Q
+
+    if Z1 == 0:
+        return affine_to_jacobian(Q)
+
+    Z1Z1 = mod_mul(Z1, Z1, p)
+    U2 = mod_mul(x2, Z1Z1, p)
+    S2 = mod_mul(y2, mod_mul(Z1, Z1Z1, p), p)
+
+    H = mod_sub(U2, X1, p)
+    HH = mod_mul(H, H, p)
+    I = mod_mul(4, HH, p)
+    J = mod_mul(H, I, p)
+    r = mod_mul(2, mod_sub(S2, Y1, p), p)
+    V = mod_mul(X1, I, p)
+
+    X3 = mod_sub(mod_sub(mod_mul(r, r, p), J, p), mod_mul(2, V, p), p)
+    Y3 = mod_sub(mod_mul(r, mod_sub(V, X3, p), p), mod_mul(2, mod_mul(Y1, J, p), p), p)
+    Z3 = mod_mul(mod_sub(mod_mul(mod_add(Z1, H, p), mod_add(Z1, H, p), p),
+                          mod_add(Z1Z1, HH, p), p), 1, p)
+
+    return (X3, Y3, Z3)
+```
+
+## GLV Endomorphism (secp256k1)
+
+### Scalar Decomposition
+
+```
+# Constants for secp256k1
+LAMBDA = 0x5363AD4CC05C30E0A5261C028812645A122E22EA20816678DF02967C1B23BD72
+BETA = 0x7AE96A2B657C07106E64479EAC3434E99CF0497512F58995C1396C28719501EE
+
+# Decomposition coefficients
+A1 = 0x3086D221A7D46BCDE86C90E49284EB15
+B1 = 0x114CA50F7A8E2F3F657C1108D9D44CFD8
+A2 = 0xE4437ED6010E88286F547FA90ABFE4C3
+B2 = A1
+
+function glv_decompose(k, n):
+    # Compute c1 = round(b2 * k / n)
+    # Compute c2 = round(-b1 * k / n)
+    c1 = (B2 * k + n // 2) // n
+    c2 = (-B1 * k + n // 2) // n
+
+    # k1 = k - c1*A1 - c2*A2
+    # k2 = -c1*B1 - c2*B2
+    k1 = k - c1 * A1 - c2 * A2
+    k2 = -c1 * B1 - c2 * B2
+
+    return (k1, k2)
+
+function glv_scalar_mult(k, P, p, n):
+    k1, k2 = glv_decompose(k, n)
+
+    # Compute endomorphism: φ(P) = (β*x, y)
+    x, y = P
+    phi_P = (mod_mul(BETA, x, p), y)
+
+    # Use Shamir's trick: k1*P + k2*φ(P)
+    return multi_scalar_mult(k1, P, k2, phi_P, 0, p)
+```
+
+## Batch Inversion
+
+Amortize expensive inversions over multiple points:
+
+```
+function batch_invert(values, p):
+    n = len(values)
+    if n == 0:
+        return []
+
+    # Compute cumulative products
+    products = [values[0]]
+    for i in range(1, n):
+        products.append(mod_mul(products[-1], values[i], p))
+
+    # Invert the final product
+    inv = mod_inverse(products[-1], p)
+
+    # Compute individual inverses
+    inverses = [0] * n
+    for i in range(n - 1, 0, -1):
+        inverses[i] = mod_mul(inv, products[i - 1], p)
+        inv = mod_mul(inv, values[i], p)
+    inverses[0] = inv
+
+    return inverses
+```
+
+## Key Generation
+
+```
+function generate_keypair(G, n, p):
+    # Generate random private key
+    d = random_integer(1, n - 1)
+
+    # Compute public key
+    Q = scalar_mult(d, G)
+
+    return (d, Q)
+```
+
+## Point Compression/Decompression
+
+```
+function compress_point(P, p):
+    if P is infinity:
+        return bytes([0x00])
+
+    x, y = P
+    prefix = 0x02 if (y % 2 == 0) else 0x03
+    return bytes([prefix]) + x.to_bytes(32, 'big')
+
+function decompress_point(compressed, a, b, p):
+    prefix = compressed[0]
+
+    if prefix == 0x00:
+        return infinity
+
+    x = int.from_bytes(compressed[1:], 'big')
+
+    # Compute y² = x³ + ax + b
+    y_squared = mod_add(mod_add(mod_mul(x, mod_mul(x, x, p), p),
+                                  mod_mul(a, x, p), p), b, p)
+
+    # Compute y = sqrt(y²)
+    y = mod_sqrt(y_squared, p)
+
+    # Select correct y based on prefix
+    if (prefix == 0x02) != (y % 2 == 0):
+        y = p - y
+
+    return (x, y)
+```

.claude/skills/elliptic-curves/references/secp256k1-parameters.md

@@ -0,0 +1,194 @@
+# secp256k1 Complete Parameters
+
+## Curve Definition
+
+**Name**: secp256k1 (Standards for Efficient Cryptography, prime field, 256-bit, Koblitz curve #1)
+
+**Equation**: y² = x³ + 7 (mod p)
+
+This is the short Weierstrass form with coefficients a = 0, b = 7.
+
+## Field Parameters
+
+### Prime Modulus p
+
+```
+Decimal:
+115792089237316195423570985008687907853269984665640564039457584007908834671663
+
+Hexadecimal:
+0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
+
+Binary representation:
+2²⁵⁶ - 2³² - 2⁹ - 2⁸ - 2⁷ - 2⁶ - 2⁴ - 1
+= 2²⁵⁶ - 2³² - 977
+```
+
+**Special form benefits**:
+- Efficient modular reduction using: c mod p = c_low + c_high × (2³² + 977)
+- Near-Mersenne prime enables fast arithmetic
+
+### Group Order n
+
+```
+Decimal:
+115792089237316195423570985008687907852837564279074904382605163141518161494337
+
+Hexadecimal:
+0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+```
+
+The number of points on the curve, including the point at infinity.
+
+### Cofactor h
+
+```
+h = 1
+```
+
+Cofactor 1 means the group order n equals the curve order, simplifying security analysis and eliminating small subgroup attacks.
+
+## Generator Point G
+
+### Compressed Form
+
+```
+02 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798
+```
+
+The 02 prefix indicates the y-coordinate is even.
+
+### Uncompressed Form
+
+```
+04 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798
+   483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8
+```
+
+### Individual Coordinates
+
+**Gx**:
+```
+Decimal:
+55066263022277343669578718895168534326250603453777594175500187360389116729240
+
+Hexadecimal:
+0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798
+```
+
+**Gy**:
+```
+Decimal:
+32670510020758816978083085130507043184471273380659243275938904335757337482424
+
+Hexadecimal:
+0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8
+```
+
+## Endomorphism Parameters
+
+secp256k1 has an efficiently computable endomorphism φ: (x, y) → (βx, y).
+
+### β (Beta)
+
+```
+Hexadecimal:
+0x7AE96A2B657C07106E64479EAC3434E99CF0497512F58995C1396C28719501EE
+
+Property: β³ ≡ 1 (mod p)
+```
+
+### λ (Lambda)
+
+```
+Hexadecimal:
+0x5363AD4CC05C30E0A5261C028812645A122E22EA20816678DF02967C1B23BD72
+
+Property: λ³ ≡ 1 (mod n)
+Relationship: φ(P) = λP for all points P
+```
+
+### GLV Decomposition Constants
+
+For splitting scalar k into k₁ + k₂λ:
+
+```
+a₁ = 0x3086D221A7D46BCDE86C90E49284EB15
+b₁ = -0xE4437ED6010E88286F547FA90ABFE4C3
+a₂ = 0x114CA50F7A8E2F3F657C1108D9D44CFD8
+b₂ = a₁
+```
+
+## Derived Constants
+
+### Field Characteristics
+
+```
+(p + 1) / 4 = 0x3FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF0C
+Used for computing modular square roots via Tonelli-Shanks shortcut
+```
+
+### Order Characteristics
+
+```
+(n - 1) / 2 = 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0
+Used in low-S normalization for ECDSA signatures
+```
+
+## Validation Formulas
+
+### Point on Curve Check
+
+For point (x, y), verify:
+```
+y² ≡ x³ + 7 (mod p)
+```
+
+### Generator Verification
+
+Verify G is on curve:
+```
+Gy² mod p = 0x9C47D08FFB10D4B8 ... (truncated for display)
+Gx³ + 7 mod p = same value
+```
+
+### Order Verification
+
+Verify nG = O (point at infinity):
+```
+Computing n × G should yield the identity element
+```
+
+## Bit Lengths
+
+| Parameter | Bits | Bytes |
+|-----------|------|-------|
+| p (prime) | 256  | 32    |
+| n (order) | 256  | 32    |
+| Private key | 256 | 32   |
+| Public key (compressed) | 257 | 33 |
+| Public key (uncompressed) | 513 | 65 |
+| ECDSA signature | 512 | 64 |
+| Schnorr signature | 512 | 64 |
+
+## Security Level
+
+- **Equivalent symmetric key strength**: 128 bits
+- **Best known attack complexity**: ~2¹²⁸ operations (Pollard's rho)
+- **Safe until**: Quantum computers with ~1500+ logical qubits
+
+## ASN.1 OID
+
+```
+1.3.132.0.10
+iso(1) identified-organization(3) certicom(132) curve(0) secp256k1(10)
+```
+
+## Comparison with Other Curves
+
+| Curve | Field Size | Security | Speed | Use Case |
+|-------|------------|----------|-------|----------|
+| secp256k1 | 256-bit | 128-bit | Fast (Koblitz) | Bitcoin, Nostr |
+| secp256r1 (P-256) | 256-bit | 128-bit | Moderate | TLS, general |
+| Curve25519 | 255-bit | ~128-bit | Very fast | Modern crypto |
+| secp384r1 (P-384) | 384-bit | 192-bit | Slower | High security |

.claude/skills/elliptic-curves/references/security.md

@@ -0,0 +1,291 @@
+# Elliptic Curve Security Analysis
+
+Security properties, attack vectors, and mitigations for elliptic curve cryptography.
+
+## The Discrete Logarithm Problem (ECDLP)
+
+### Definition
+
+Given points P and Q = kP on an elliptic curve, find the scalar k.
+
+**Security assumption**: For properly chosen curves, this problem is computationally infeasible.
+
+### Best Known Attacks
+
+#### Generic Attacks (Work on Any Group)
+
+| Attack | Complexity | Notes |
+|--------|------------|-------|
+| Baby-step Giant-step | O(√n) space and time | Requires √n storage |
+| Pollard's rho | O(√n) time, O(1) space | Practical for large groups |
+| Pollard's lambda | O(√n) | When k is in known range |
+| Pohlig-Hellman | O(√p) where p is largest prime factor | Exploits factorization of n |
+
+For secp256k1 (n ≈ 2²⁵⁶):
+- Generic attack complexity: ~2¹²⁸ operations
+- Equivalent to 128-bit symmetric security
+
+#### Curve-Specific Attacks
+
+| Attack | Applicable When | Mitigation |
+|--------|-----------------|------------|
+| MOV/FR reduction | Low embedding degree | Use curves with high embedding degree |
+| Anomalous curve attack | n = p | Ensure n ≠ p |
+| GHS attack | Extension field curves | Use prime field curves |
+
+**secp256k1 is immune to all known curve-specific attacks**.
+
+## Side-Channel Attacks
+
+### Timing Attacks
+
+**Vulnerability**: Execution time varies based on secret data.
+
+**Examples**:
+- Conditional branches on secret bits
+- Early exit conditions
+- Variable-time modular operations
+
+**Mitigations**:
+- Constant-time algorithms (Montgomery ladder)
+- Fixed execution paths
+- Dummy operations to equalize timing
+
+### Power Analysis
+
+**Simple Power Analysis (SPA)**: Single trace reveals operations.
+- Double-and-add visible as different power signatures
+- Mitigation: Montgomery ladder (uniform operations)
+
+**Differential Power Analysis (DPA)**: Statistical analysis of many traces.
+- Mitigation: Point blinding, scalar blinding
+
+### Cache Attacks
+
+**FLUSH+RELOAD Attack**:
+```
+1. Attacker flushes cache line containing lookup table
+2. Victim performs table lookup based on secret
+3. Attacker measures reload time to determine which entry was accessed
+```
+
+**Mitigations**:
+- Avoid secret-dependent table lookups
+- Use constant-time table access patterns
+- Scatter tables to prevent cache line sharing
+
+### Electromagnetic (EM) Attacks
+
+Similar to power analysis but captures electromagnetic emissions.
+
+**Mitigations**:
+- Shielding
+- Same algorithmic protections as power analysis
+
+## Implementation Vulnerabilities
+
+### k-Reuse in ECDSA
+
+**The Sony PS3 Hack (2010)**:
+
+If the same k is used for two signatures (r₁, s₁) and (r₂, s₂) on messages m₁ and m₂:
+
+```
+s₁ = k⁻¹(e₁ + rd) mod n
+s₂ = k⁻¹(e₂ + rd) mod n
+
+Since k is the same:
+s₁ - s₂ = k⁻¹(e₁ - e₂) mod n
+k = (e₁ - e₂)(s₁ - s₂)⁻¹ mod n
+
+Once k is known:
+d = (s₁k - e₁)r⁻¹ mod n
+```
+
+**Mitigation**: Use deterministic k (RFC 6979).
+
+### Weak Random k
+
+Even with unique k values, if the RNG is biased:
+- Lattice-based attacks can recover private key
+- Only ~1% bias in k can be exploitable with enough signatures
+
+**Mitigations**:
+- Use cryptographically secure RNG
+- Use deterministic k (RFC 6979)
+- Verify k is in valid range [1, n-1]
+
+### Invalid Curve Attacks
+
+**Attack**: Attacker provides point not on the curve.
+- Point may be on a weaker curve
+- Operations may leak information
+
+**Mitigation**: Always validate points are on curve:
+```
+Verify: y² ≡ x³ + ax + b (mod p)
+```
+
+### Small Subgroup Attacks
+
+**Attack**: If cofactor h > 1, points of small order exist.
+- Attacker sends point of small order
+- Response reveals private key mod (small order)
+
+**Mitigation**:
+- Use curves with cofactor 1 (secp256k1 has h = 1)
+- Multiply received points by cofactor
+- Validate point order
+
+### Fault Attacks
+
+**Attack**: Induce computational errors (voltage glitches, radiation).
+- Corrupted intermediate values may leak information
+- Differential fault analysis can recover keys
+
+**Mitigations**:
+- Redundant computations with comparison
+- Verify final results
+- Hardware protections
+
+## Signature Malleability
+
+### ECDSA Malleability
+
+Given valid signature (r, s), signature (r, n - s) is also valid for the same message.
+
+**Impact**: Transaction ID malleability (historical Bitcoin issue)
+
+**Mitigation**: Enforce low-S normalization:
+```
+if s > n/2:
+    s = n - s
+```
+
+### Schnorr Non-Malleability
+
+BIP-340 Schnorr signatures are non-malleable by design:
+- Use x-only public keys
+- Deterministic nonce derivation
+
+## Quantum Threats
+
+### Shor's Algorithm
+
+**Threat**: Polynomial-time discrete log on quantum computers.
+- Requires ~1500-2000 logical qubits for secp256k1
+- Current quantum computers: <100 noisy qubits
+
+**Timeline**: Estimated 10-20+ years for cryptographically relevant quantum computers.
+
+### Migration Strategy
+
+1. **Monitor**: Track quantum computing progress
+2. **Prepare**: Develop post-quantum alternatives
+3. **Hybrid**: Use classical + post-quantum in transition
+4. **Migrate**: Full transition when necessary
+
+### Post-Quantum Alternatives
+
+- Lattice-based signatures (CRYSTALS-Dilithium)
+- Hash-based signatures (SPHINCS+)
+- Code-based cryptography
+
+## Best Practices
+
+### Key Generation
+
+```
+DO:
+- Use cryptographically secure RNG
+- Validate private key is in [1, n-1]
+- Verify public key is on curve
+- Verify public key is not point at infinity
+
+DON'T:
+- Use predictable seeds
+- Use truncated random values
+- Skip validation
+```
+
+### Signature Generation
+
+```
+DO:
+- Use RFC 6979 for deterministic k
+- Validate all inputs
+- Use constant-time operations
+- Clear sensitive memory after use
+
+DON'T:
+- Reuse k values
+- Use weak/biased RNG
+- Skip low-S normalization (ECDSA)
+```
+
+### Signature Verification
+
+```
+DO:
+- Validate r, s are in [1, n-1]
+- Validate public key is on curve
+- Validate public key is not infinity
+- Use batch verification when possible
+
+DON'T:
+- Skip any validation steps
+- Accept malformed signatures
+```
+
+### Public Key Handling
+
+```
+DO:
+- Validate received points are on curve
+- Check point is not infinity
+- Prefer compressed format for storage
+
+DON'T:
+- Accept unvalidated points
+- Skip curve membership check
+```
+
+## Security Checklist
+
+### Implementation Review
+
+- [ ] All scalar multiplications are constant-time
+- [ ] No secret-dependent branches
+- [ ] No secret-indexed table lookups
+- [ ] Memory is zeroized after use
+- [ ] Random k uses CSPRNG or RFC 6979
+- [ ] All received points are validated
+- [ ] Private keys are in valid range
+- [ ] Signatures use low-S normalization
+
+### Operational Security
+
+- [ ] Private keys stored securely (HSM, secure enclave)
+- [ ] Key derivation uses proper KDF
+- [ ] Backups are encrypted
+- [ ] Key rotation policy exists
+- [ ] Audit logging enabled
+- [ ] Incident response plan exists
+
+## Security Levels Comparison
+
+| Curve | Bits | Symmetric Equivalent | RSA Equivalent |
+|-------|------|---------------------|----------------|
+| secp192r1 | 192 | 96 | 1536 |
+| secp224r1 | 224 | 112 | 2048 |
+| secp256k1 | 256 | 128 | 3072 |
+| secp384r1 | 384 | 192 | 7680 |
+| secp521r1 | 521 | 256 | 15360 |
+
+## References
+
+- NIST SP 800-57: Recommendation for Key Management
+- SEC 1: Elliptic Curve Cryptography
+- RFC 6979: Deterministic Usage of DSA and ECDSA
+- BIP-340: Schnorr Signatures for secp256k1
+- SafeCurves: Choosing Safe Curves for Elliptic-Curve Cryptography

.claude/skills/go-memory-optimization/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: go-memory-optimization
+description: This skill should be used when optimizing Go code for memory efficiency, reducing GC pressure, implementing object pooling, analyzing escape behavior, choosing between fixed-size arrays and slices, designing worker pools, or profiling memory allocations. Provides comprehensive knowledge of Go's memory model, stack vs heap allocation, sync.Pool patterns, goroutine reuse, and GC tuning.
+---
+
+# Go Memory Optimization
+
+## Overview
+
+This skill provides guidance on optimizing Go programs for memory efficiency and reduced garbage collection overhead. Topics include stack allocation semantics, fixed-size types, escape analysis, object pooling, goroutine management, and GC tuning.
+
+## Core Principles
+
+### The Allocation Hierarchy
+
+Prefer allocations in this order (fastest to slowest):
+
+1. **Stack allocation** - Zero GC cost, automatic cleanup on function return
+2. **Pooled objects** - Amortized allocation cost via sync.Pool
+3. **Pre-allocated buffers** - Single allocation, reused across operations
+4. **Heap allocation** - GC-managed, use when lifetime exceeds function scope
+
+### When Optimization Matters
+
+Focus memory optimization efforts on:
+- Hot paths executed thousands/millions of times per second
+- Large objects (>32KB) that stress the GC
+- Long-running services where GC pauses affect latency
+- Memory-constrained environments
+
+Avoid premature optimization. Profile first with `go tool pprof` to identify actual bottlenecks.
+
+## Fixed-Size Types vs Slices
+
+### Stack Allocation with Arrays
+
+Arrays with known compile-time size can be stack-allocated, avoiding heap entirely:
+
+```go
+// HEAP: slice header + backing array escape to heap
+func processSlice() []byte {
+    data := make([]byte, 32)
+    // ... use data
+    return data  // escapes
+}
+
+// STACK: fixed array stays on stack if doesn't escape
+func processArray() {
+    var data [32]byte  // stack-allocated
+    // ... use data
+}   // automatically cleaned up
+```
+
+### Fixed-Size Binary Types Pattern
+
+Define types with explicit sizes for protocol fields, cryptographic values, and identifiers:
+
+```go
+// Binary types enforce length and enable stack allocation
+type EventID [32]byte      // SHA256 hash
+type Pubkey [32]byte       // Schnorr public key
+type Signature [64]byte    // Schnorr signature
+
+// Methods operate on value receivers when size permits
+func (id EventID) Hex() string {
+    return hex.EncodeToString(id[:])
+}
+
+func (id EventID) IsZero() bool {
+    return id == EventID{}  // efficient zero-value comparison
+}
+```
+
+### Size Thresholds
+
+| Size | Recommendation |
+|------|----------------|
+| ≤64 bytes | Pass by value, stack-friendly |
+| 65-128 bytes | Consider context; value for read-only, pointer for mutation |
+| >128 bytes | Pass by pointer to avoid copy overhead |
+
+### Array to Slice Conversion
+
+Convert fixed arrays to slices only at API boundaries:
+
+```go
+type Hash [32]byte
+
+func (h Hash) Bytes() []byte {
+    return h[:]  // creates slice header, array stays on stack if h does
+}
+
+// Prefer methods that accept arrays directly
+func VerifySignature(pubkey Pubkey, msg []byte, sig Signature) bool {
+    // pubkey and sig are stack-allocated in caller
+}
+```
+
+## Escape Analysis
+
+### Understanding Escape
+
+Variables "escape" to the heap when the compiler cannot prove their lifetime is bounded by the stack frame. Check escape behavior with:
+
+```bash
+go build -gcflags="-m -m" ./...
+```
+
+### Common Escape Causes
+
+```go
+// 1. Returning pointers to local variables
+func escapes() *int {
+    x := 42
+    return &x  // x escapes
+}
+
+// 2. Storing in interface{}
+func escapes(x int) interface{} {
+    return x  // x escapes (boxed)
+}
+
+// 3. Closures capturing by reference
+func escapes() func() int {
+    x := 42
+    return func() int { return x }  // x escapes
+}
+
+// 4. Slice/map with unknown capacity
+func escapes(n int) []byte {
+    return make([]byte, n)  // escapes (size unknown at compile time)
+}
+
+// 5. Sending pointers to channels
+func escapes(ch chan *int) {
+    x := 42
+    ch <- &x  // x escapes
+}
+```
+
+### Preventing Escape
+
+```go
+// 1. Accept pointers, don't return them
+func noEscape(result *[32]byte) {
+    // caller owns memory, function fills it
+    copy(result[:], computeHash())
+}
+
+// 2. Use fixed-size arrays
+func noEscape() {
+    var buf [1024]byte  // known size, stack-allocated
+    process(buf[:])
+}
+
+// 3. Preallocate with known capacity
+func noEscape() {
+    buf := make([]byte, 0, 1024)  // may stay on stack
+    // ... append up to 1024 bytes
+}
+
+// 4. Avoid interface{} on hot paths
+func noEscape(x int) int {
+    return x * 2  // no boxing
+}
+```
+
+## sync.Pool Usage
+
+### Basic Pattern
+
+```go
+var bufferPool = sync.Pool{
+    New: func() interface{} {
+        return make([]byte, 0, 4096)
+    },
+}
+
+func processRequest(data []byte) {
+    buf := bufferPool.Get().([]byte)
+    buf = buf[:0]  // reset length, keep capacity
+    defer bufferPool.Put(buf)
+
+    // use buf...
+}
+```
+
+### Typed Pool Wrapper
+
+```go
+type BufferPool struct {
+    pool sync.Pool
+    size int
+}
+
+func NewBufferPool(size int) *BufferPool {
+    return &BufferPool{
+        pool: sync.Pool{
+            New: func() interface{} {
+                b := make([]byte, size)
+                return &b
+            },
+        },
+        size: size,
+    }
+}
+
+func (p *BufferPool) Get() *[]byte {
+    return p.pool.Get().(*[]byte)
+}
+
+func (p *BufferPool) Put(b *[]byte) {
+    if b == nil || cap(*b) < p.size {
+        return  // don't pool undersized buffers
+    }
+    *b = (*b)[:p.size]  // reset to full size
+    p.pool.Put(b)
+}
+```
+
+### Pool Anti-Patterns
+
+```go
+// BAD: Pool of pointers to small values (overhead exceeds benefit)
+var intPool = sync.Pool{New: func() interface{} { return new(int) }}
+
+// BAD: Not resetting state before Put
+bufPool.Put(buf)  // may contain sensitive data
+
+// BAD: Pooling objects with goroutine-local state
+var connPool = sync.Pool{...}  // connections are stateful
+
+// BAD: Assuming pooled objects persist (GC clears pools)
+obj := pool.Get()
+// ... long delay
+pool.Put(obj)  // obj may have been GC'd during delay
+```
+
+### When to Use sync.Pool
+
+| Use Case | Pool? | Reason |
+|----------|-------|--------|
+| Buffers in HTTP handlers | Yes | High allocation rate, short lifetime |
+| Encoder/decoder state | Yes | Expensive to initialize |
+| Small values (<64 bytes) | No | Pointer overhead exceeds benefit |
+| Long-lived objects | No | Pools are for short-lived reuse |
+| Objects with cleanup needs | No | Pool provides no finalization |
+
+## Goroutine Pooling
+
+### Worker Pool Pattern
+
+```go
+type WorkerPool struct {
+    jobs    chan func()
+    workers int
+    wg      sync.WaitGroup
+}
+
+func NewWorkerPool(workers, queueSize int) *WorkerPool {
+    p := &WorkerPool{
+        jobs:    make(chan func(), queueSize),
+        workers: workers,
+    }
+    p.wg.Add(workers)
+    for i := 0; i < workers; i++ {
+        go p.worker()
+    }
+    return p
+}
+
+func (p *WorkerPool) worker() {
+    defer p.wg.Done()
+    for job := range p.jobs {
+        job()
+    }
+}
+
+func (p *WorkerPool) Submit(job func()) {
+    p.jobs <- job
+}
+
+func (p *WorkerPool) Shutdown() {
+    close(p.jobs)
+    p.wg.Wait()
+}
+```
+
+### Bounded Concurrency with Semaphore
+
+```go
+type Semaphore struct {
+    sem chan struct{}
+}
+
+func NewSemaphore(n int) *Semaphore {
+    return &Semaphore{sem: make(chan struct{}, n)}
+}
+
+func (s *Semaphore) Acquire() { s.sem <- struct{}{} }
+func (s *Semaphore) Release() { <-s.sem }
+
+// Usage
+sem := NewSemaphore(runtime.GOMAXPROCS(0))
+for _, item := range items {
+    sem.Acquire()
+    go func(it Item) {
+        defer sem.Release()
+        process(it)
+    }(item)
+}
+```
+
+### Goroutine Reuse Benefits
+
+| Metric | Spawn per request | Worker pool |
+|--------|-------------------|-------------|
+| Goroutine creation | O(n) | O(workers) |
+| Stack allocation | 2KB × n | 2KB × workers |
+| Scheduler overhead | Higher | Lower |
+| GC pressure | Higher | Lower |
+
+## Reducing GC Pressure
+
+### Allocation Reduction Strategies
+
+```go
+// 1. Reuse buffers across iterations
+buf := make([]byte, 0, 4096)
+for _, item := range items {
+    buf = buf[:0]  // reset without reallocation
+    buf = processItem(buf, item)
+}
+
+// 2. Preallocate slices with known length
+result := make([]Item, 0, len(input))  // avoid append reallocations
+for _, in := range input {
+    result = append(result, transform(in))
+}
+
+// 3. Struct embedding instead of pointer fields
+type Event struct {
+    ID        [32]byte    // embedded, not *[32]byte
+    Pubkey    [32]byte    // single allocation for entire struct
+    Signature [64]byte
+    Content   string      // only string data on heap
+}
+
+// 4. String interning for repeated values
+var kindStrings = map[int]string{
+    0: "set_metadata",
+    1: "text_note",
+    // ...
+}
+```
+
+### GC Tuning
+
+```go
+import "runtime/debug"
+
+func init() {
+    // GOGC: target heap growth percentage (default 100)
+    // Lower = more frequent GC, less memory
+    // Higher = less frequent GC, more memory
+    debug.SetGCPercent(50)  // GC when heap grows 50%
+
+    // GOMEMLIMIT: soft memory limit (Go 1.19+)
+    // GC becomes more aggressive as limit approaches
+    debug.SetMemoryLimit(512 << 20)  // 512MB limit
+}
+```
+
+Environment variables:
+
+```bash
+GOGC=50              # More aggressive GC
+GOMEMLIMIT=512MiB    # Soft memory limit
+GODEBUG=gctrace=1    # GC trace output
+```
+
+### Arena Allocation (Go 1.20+, experimental)
+
+```go
+//go:build goexperiment.arenas
+
+import "arena"
+
+func processLargeDataset(data []byte) Result {
+    a := arena.NewArena()
+    defer a.Free()  // bulk free all allocations
+
+    // All allocations from arena are freed together
+    items := arena.MakeSlice[Item](a, 0, 1000)
+    // ... process
+
+    // Copy result out before Free
+    return copyResult(result)
+}
+```
+
+## Memory Profiling
+
+### Heap Profile
+
+```go
+import "runtime/pprof"
+
+func captureHeapProfile() {
+    f, _ := os.Create("heap.prof")
+    defer f.Close()
+    runtime.GC()  // get accurate picture
+    pprof.WriteHeapProfile(f)
+}
+```
+
+```bash
+go tool pprof -http=:8080 heap.prof
+go tool pprof -alloc_space heap.prof  # total allocations
+go tool pprof -inuse_space heap.prof  # current usage
+```
+
+### Allocation Benchmarks
+
+```go
+func BenchmarkAllocation(b *testing.B) {
+    b.ReportAllocs()
+    for i := 0; i < b.N; i++ {
+        result := processData(input)
+        _ = result
+    }
+}
+```
+
+Output interpretation:
+
+```
+BenchmarkAllocation-8  1000000  1234 ns/op  256 B/op  3 allocs/op
+                                            ↑         ↑
+                                   bytes/op   allocations/op
+```
+
+### Live Memory Monitoring
+
+```go
+func printMemStats() {
+    var m runtime.MemStats
+    runtime.ReadMemStats(&m)
+    fmt.Printf("Alloc: %d MB\n", m.Alloc/1024/1024)
+    fmt.Printf("TotalAlloc: %d MB\n", m.TotalAlloc/1024/1024)
+    fmt.Printf("Sys: %d MB\n", m.Sys/1024/1024)
+    fmt.Printf("NumGC: %d\n", m.NumGC)
+    fmt.Printf("GCPause: %v\n", time.Duration(m.PauseNs[(m.NumGC+255)%256]))
+}
+```
+
+## Common Patterns Reference
+
+For detailed code examples and patterns, see `references/patterns.md`:
+
+- Buffer pool implementations
+- Zero-allocation JSON encoding
+- Memory-efficient string building
+- Slice capacity management
+- Struct layout optimization
+
+## Checklist for Memory-Critical Code
+
+1. [ ] Profile before optimizing (`go tool pprof`)
+2. [ ] Check escape analysis output (`-gcflags="-m"`)
+3. [ ] Use fixed-size arrays for known-size data
+4. [ ] Implement sync.Pool for frequently allocated objects
+5. [ ] Preallocate slices with known capacity
+6. [ ] Reuse buffers instead of allocating new ones
+7. [ ] Consider struct field ordering for alignment
+8. [ ] Benchmark with `-benchmem` flag
+9. [ ] Set appropriate GOGC/GOMEMLIMIT for production
+10. [ ] Monitor GC behavior with GODEBUG=gctrace=1

.claude/skills/go-memory-optimization/references/patterns.md

@@ -0,0 +1,594 @@
+# Go Memory Optimization Patterns
+
+Detailed code examples and patterns for memory-efficient Go programming.
+
+## Buffer Pool Implementations
+
+### Tiered Buffer Pool
+
+For workloads with varying buffer sizes:
+
+```go
+type TieredPool struct {
+    small  sync.Pool  // 1KB
+    medium sync.Pool  // 16KB
+    large  sync.Pool  // 256KB
+}
+
+func NewTieredPool() *TieredPool {
+    return &TieredPool{
+        small:  sync.Pool{New: func() interface{} { return make([]byte, 1024) }},
+        medium: sync.Pool{New: func() interface{} { return make([]byte, 16384) }},
+        large:  sync.Pool{New: func() interface{} { return make([]byte, 262144) }},
+    }
+}
+
+func (p *TieredPool) Get(size int) []byte {
+    switch {
+    case size <= 1024:
+        return p.small.Get().([]byte)[:size]
+    case size <= 16384:
+        return p.medium.Get().([]byte)[:size]
+    case size <= 262144:
+        return p.large.Get().([]byte)[:size]
+    default:
+        return make([]byte, size)  // too large for pool
+    }
+}
+
+func (p *TieredPool) Put(b []byte) {
+    switch cap(b) {
+    case 1024:
+        p.small.Put(b[:cap(b)])
+    case 16384:
+        p.medium.Put(b[:cap(b)])
+    case 262144:
+        p.large.Put(b[:cap(b)])
+    }
+    // Non-standard sizes are not pooled
+}
+```
+
+### bytes.Buffer Pool
+
+```go
+var bufferPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func GetBuffer() *bytes.Buffer {
+    return bufferPool.Get().(*bytes.Buffer)
+}
+
+func PutBuffer(b *bytes.Buffer) {
+    b.Reset()
+    bufferPool.Put(b)
+}
+
+// Usage
+func processData(data []byte) string {
+    buf := GetBuffer()
+    defer PutBuffer(buf)
+
+    buf.WriteString("prefix:")
+    buf.Write(data)
+    buf.WriteString(":suffix")
+
+    return buf.String()  // allocates new string
+}
+```
+
+## Zero-Allocation JSON Encoding
+
+### Pre-allocated Encoder
+
+```go
+type JSONEncoder struct {
+    buf    []byte
+    scratch [64]byte  // for number formatting
+}
+
+func (e *JSONEncoder) Reset() {
+    e.buf = e.buf[:0]
+}
+
+func (e *JSONEncoder) Bytes() []byte {
+    return e.buf
+}
+
+func (e *JSONEncoder) WriteString(s string) {
+    e.buf = append(e.buf, '"')
+    for i := 0; i < len(s); i++ {
+        c := s[i]
+        switch c {
+        case '"':
+            e.buf = append(e.buf, '\\', '"')
+        case '\\':
+            e.buf = append(e.buf, '\\', '\\')
+        case '\n':
+            e.buf = append(e.buf, '\\', 'n')
+        case '\r':
+            e.buf = append(e.buf, '\\', 'r')
+        case '\t':
+            e.buf = append(e.buf, '\\', 't')
+        default:
+            if c < 0x20 {
+                e.buf = append(e.buf, '\\', 'u', '0', '0',
+                    hexDigits[c>>4], hexDigits[c&0xf])
+            } else {
+                e.buf = append(e.buf, c)
+            }
+        }
+    }
+    e.buf = append(e.buf, '"')
+}
+
+func (e *JSONEncoder) WriteInt(n int64) {
+    e.buf = strconv.AppendInt(e.buf, n, 10)
+}
+
+func (e *JSONEncoder) WriteHex(b []byte) {
+    e.buf = append(e.buf, '"')
+    for _, v := range b {
+        e.buf = append(e.buf, hexDigits[v>>4], hexDigits[v&0xf])
+    }
+    e.buf = append(e.buf, '"')
+}
+
+var hexDigits = [16]byte{'0', '1', '2', '3', '4', '5', '6', '7',
+                          '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'}
+```
+
+### Append-Based Encoding
+
+```go
+// AppendJSON appends JSON representation to dst, returning extended slice
+func (ev *Event) AppendJSON(dst []byte) []byte {
+    dst = append(dst, `{"id":"`...)
+    dst = appendHex(dst, ev.ID[:])
+    dst = append(dst, `","pubkey":"`...)
+    dst = appendHex(dst, ev.Pubkey[:])
+    dst = append(dst, `","created_at":`...)
+    dst = strconv.AppendInt(dst, ev.CreatedAt, 10)
+    dst = append(dst, `,"kind":`...)
+    dst = strconv.AppendInt(dst, int64(ev.Kind), 10)
+    dst = append(dst, `,"content":`...)
+    dst = appendJSONString(dst, ev.Content)
+    dst = append(dst, '}')
+    return dst
+}
+
+// Usage with pre-allocated buffer
+func encodeEvents(events []Event) []byte {
+    // Estimate size: ~500 bytes per event
+    buf := make([]byte, 0, len(events)*500)
+    buf = append(buf, '[')
+    for i, ev := range events {
+        if i > 0 {
+            buf = append(buf, ',')
+        }
+        buf = ev.AppendJSON(buf)
+    }
+    buf = append(buf, ']')
+    return buf
+}
+```
+
+## Memory-Efficient String Building
+
+### strings.Builder with Preallocation
+
+```go
+func buildQuery(parts []string) string {
+    // Calculate total length
+    total := len(parts) - 1  // for separators
+    for _, p := range parts {
+        total += len(p)
+    }
+
+    var b strings.Builder
+    b.Grow(total)  // single allocation
+
+    for i, p := range parts {
+        if i > 0 {
+            b.WriteByte(',')
+        }
+        b.WriteString(p)
+    }
+    return b.String()
+}
+```
+
+### Avoiding String Concatenation
+
+```go
+// BAD: O(n^2) allocations
+func buildPath(parts []string) string {
+    result := ""
+    for _, p := range parts {
+        result += "/" + p  // new allocation each iteration
+    }
+    return result
+}
+
+// GOOD: O(n) with single allocation
+func buildPath(parts []string) string {
+    if len(parts) == 0 {
+        return ""
+    }
+    n := len(parts)  // for slashes
+    for _, p := range parts {
+        n += len(p)
+    }
+
+    b := make([]byte, 0, n)
+    for _, p := range parts {
+        b = append(b, '/')
+        b = append(b, p...)
+    }
+    return string(b)
+}
+```
+
+### Unsafe String/Byte Conversion
+
+```go
+import "unsafe"
+
+// Zero-allocation string to []byte (read-only!)
+func unsafeBytes(s string) []byte {
+    return unsafe.Slice(unsafe.StringData(s), len(s))
+}
+
+// Zero-allocation []byte to string (b must not be modified!)
+func unsafeString(b []byte) string {
+    return unsafe.String(unsafe.SliceData(b), len(b))
+}
+
+// Use when:
+// 1. Converting string for read-only operations (hashing, comparison)
+// 2. Returning []byte from buffer that won't be modified
+// 3. Performance-critical paths with careful ownership management
+```
+
+## Slice Capacity Management
+
+### Append Growth Patterns
+
+```go
+// Slice growth: 0 -> 1 -> 2 -> 4 -> 8 -> 16 -> 32 -> 64 -> ...
+// After 1024: grows by 25% each time
+
+// BAD: Unknown final size causes multiple reallocations
+func collectItems() []Item {
+    var items []Item
+    for item := range source {
+        items = append(items, item)  // may reallocate multiple times
+    }
+    return items
+}
+
+// GOOD: Preallocate when size is known
+func collectItems(n int) []Item {
+    items := make([]Item, 0, n)
+    for item := range source {
+        items = append(items, item)
+    }
+    return items
+}
+
+// GOOD: Use slice header trick for uncertain sizes
+func collectItems() []Item {
+    items := make([]Item, 0, 32)  // reasonable initial capacity
+    for item := range source {
+        items = append(items, item)
+    }
+    // Trim excess capacity if items will be long-lived
+    return items[:len(items):len(items)]
+}
+```
+
+### Slice Recycling
+
+```go
+// Reuse slice backing array
+func processInBatches(items []Item, batchSize int) {
+    batch := make([]Item, 0, batchSize)
+
+    for i, item := range items {
+        batch = append(batch, item)
+
+        if len(batch) == batchSize || i == len(items)-1 {
+            processBatch(batch)
+            batch = batch[:0]  // reset length, keep capacity
+        }
+    }
+}
+```
+
+### Preventing Slice Memory Leaks
+
+```go
+// BAD: Subslice keeps entire backing array alive
+func getFirst10(data []byte) []byte {
+    return data[:10]  // entire data array stays in memory
+}
+
+// GOOD: Copy to release original array
+func getFirst10(data []byte) []byte {
+    result := make([]byte, 10)
+    copy(result, data[:10])
+    return result
+}
+
+// Alternative: explicit capacity limit
+func getFirst10(data []byte) []byte {
+    return data[:10:10]  // cap=10, can't accidentally grow into original
+}
+```
+
+## Struct Layout Optimization
+
+### Field Ordering for Alignment
+
+```go
+// BAD: 32 bytes due to padding
+type BadLayout struct {
+    a bool      // 1 byte + 7 padding
+    b int64     // 8 bytes
+    c bool      // 1 byte + 7 padding
+    d int64     // 8 bytes
+}
+
+// GOOD: 24 bytes with optimal ordering
+type GoodLayout struct {
+    b int64     // 8 bytes
+    d int64     // 8 bytes
+    a bool      // 1 byte
+    c bool      // 1 byte + 6 padding
+}
+
+// Rule: Order fields from largest to smallest alignment
+```
+
+### Checking Struct Size
+
+```go
+func init() {
+    // Compile-time size assertions
+    var _ [24]byte = [unsafe.Sizeof(GoodLayout{})]byte{}
+
+    // Or runtime check
+    if unsafe.Sizeof(Event{}) > 256 {
+        panic("Event struct too large")
+    }
+}
+```
+
+### Cache-Line Optimization
+
+```go
+const CacheLineSize = 64
+
+// Pad struct to prevent false sharing in concurrent access
+type PaddedCounter struct {
+    value uint64
+    _     [CacheLineSize - 8]byte  // padding
+}
+
+type Counters struct {
+    reads  PaddedCounter
+    writes PaddedCounter
+    // Each counter on separate cache line
+}
+```
+
+## Object Reuse Patterns
+
+### Reset Methods
+
+```go
+type Request struct {
+    Method  string
+    Path    string
+    Headers map[string]string
+    Body    []byte
+}
+
+func (r *Request) Reset() {
+    r.Method = ""
+    r.Path = ""
+    // Reuse map, just clear entries
+    for k := range r.Headers {
+        delete(r.Headers, k)
+    }
+    r.Body = r.Body[:0]
+}
+
+var requestPool = sync.Pool{
+    New: func() interface{} {
+        return &Request{
+            Headers: make(map[string]string, 8),
+            Body:    make([]byte, 0, 1024),
+        }
+    },
+}
+```
+
+### Flyweight Pattern
+
+```go
+// Share immutable parts across many instances
+type Event struct {
+    kind    *Kind   // shared, immutable
+    content string
+}
+
+type Kind struct {
+    ID          int
+    Name        string
+    Description string
+}
+
+var kindRegistry = map[int]*Kind{
+    0: {0, "set_metadata", "User metadata"},
+    1: {1, "text_note", "Text note"},
+    // ... pre-allocated, shared across all events
+}
+
+func NewEvent(kindID int, content string) Event {
+    return Event{
+        kind:    kindRegistry[kindID],  // no allocation
+        content: content,
+    }
+}
+```
+
+## Channel Patterns for Memory Efficiency
+
+### Buffered Channels as Object Pools
+
+```go
+type SimplePool struct {
+    pool chan *Buffer
+}
+
+func NewSimplePool(size int) *SimplePool {
+    p := &SimplePool{pool: make(chan *Buffer, size)}
+    for i := 0; i < size; i++ {
+        p.pool <- NewBuffer()
+    }
+    return p
+}
+
+func (p *SimplePool) Get() *Buffer {
+    select {
+    case b := <-p.pool:
+        return b
+    default:
+        return NewBuffer()  // pool empty, allocate new
+    }
+}
+
+func (p *SimplePool) Put(b *Buffer) {
+    select {
+    case p.pool <- b:
+    default:
+        // pool full, let GC collect
+    }
+}
+```
+
+### Batch Processing Channels
+
+```go
+// Reduce channel overhead by batching
+func batchProcessor(input <-chan Item, batchSize int) <-chan []Item {
+    output := make(chan []Item)
+    go func() {
+        defer close(output)
+        batch := make([]Item, 0, batchSize)
+
+        for item := range input {
+            batch = append(batch, item)
+            if len(batch) == batchSize {
+                output <- batch
+                batch = make([]Item, 0, batchSize)
+            }
+        }
+        if len(batch) > 0 {
+            output <- batch
+        }
+    }()
+    return output
+}
+```
+
+## Advanced Techniques
+
+### Manual Memory Management with mmap
+
+```go
+import "golang.org/x/sys/unix"
+
+// Allocate memory outside Go heap
+func allocateMmap(size int) ([]byte, error) {
+    data, err := unix.Mmap(-1, 0, size,
+        unix.PROT_READ|unix.PROT_WRITE,
+        unix.MAP_ANON|unix.MAP_PRIVATE)
+    return data, err
+}
+
+func freeMmap(data []byte) error {
+    return unix.Munmap(data)
+}
+```
+
+### Inline Arrays in Structs
+
+```go
+// Small-size optimization: inline for small, pointer for large
+type SmallVec struct {
+    len   int
+    small [8]int      // inline storage for ≤8 elements
+    large []int       // heap storage for >8 elements
+}
+
+func (v *SmallVec) Append(x int) {
+    if v.large != nil {
+        v.large = append(v.large, x)
+        v.len++
+        return
+    }
+    if v.len < 8 {
+        v.small[v.len] = x
+        v.len++
+        return
+    }
+    // Spill to heap
+    v.large = make([]int, 9, 16)
+    copy(v.large, v.small[:])
+    v.large[8] = x
+    v.len++
+}
+```
+
+### Bump Allocator
+
+```go
+// Simple arena-style allocator for batch allocations
+type BumpAllocator struct {
+    buf []byte
+    off int
+}
+
+func NewBumpAllocator(size int) *BumpAllocator {
+    return &BumpAllocator{buf: make([]byte, size)}
+}
+
+func (a *BumpAllocator) Alloc(size int) []byte {
+    if a.off+size > len(a.buf) {
+        panic("bump allocator exhausted")
+    }
+    b := a.buf[a.off : a.off+size]
+    a.off += size
+    return b
+}
+
+func (a *BumpAllocator) Reset() {
+    a.off = 0
+}
+
+// Usage: allocate many small objects, reset all at once
+func processBatch(items []Item) {
+    arena := NewBumpAllocator(1 << 20)  // 1MB
+    defer arena.Reset()
+
+    for _, item := range items {
+        buf := arena.Alloc(item.Size())
+        item.Serialize(buf)
+    }
+}
+```

.claude/skills/golang/SKILL.md

@@ -82,6 +82,49 @@ func (f *File) Read(p []byte) (n int, err error) {
 }
 ```
 
+### Interface Design - CRITICAL RULES
+
+**Rule 1: Define interfaces in a dedicated package (e.g., `pkg/interfaces/<name>/`)**
+- Interfaces provide isolation between packages and enable dependency inversion
+- Keeping interfaces in a dedicated package prevents circular dependencies
+- Each interface package should be minimal (just the interface, no implementations)
+
+**Rule 2: NEVER use type assertions with interface literals**
+- **NEVER** write `.(interface{ Method() Type })` - this is non-idiomatic and unmaintainable
+- Interface literals cannot be documented, tested for satisfaction, or reused
+
+```go
+// BAD - interface literal in type assertion (NEVER DO THIS)
+if checker, ok := obj.(interface{ Check() bool }); ok {
+    checker.Check()
+}
+
+// GOOD - use defined interface from dedicated package
+import "myproject/pkg/interfaces/checker"
+
+if c, ok := obj.(checker.Checker); ok {
+    c.Check()
+}
+```
+
+**Rule 3: Resolving Circular Dependencies**
+- If a circular dependency occurs, move the interface to `pkg/interfaces/`
+- The implementing type stays in its original package
+- The consuming code imports only the interface package
+- Pattern:
+  ```
+  pkg/interfaces/foo/   <- interface definition (no dependencies)
+       ↑           ↑
+  pkg/bar/         pkg/baz/
+  (implements)     (consumes via interface)
+  ```
+
+**Rule 4: Verify interface satisfaction at compile time**
+```go
+// Add this line to ensure *MyType implements MyInterface
+var _ MyInterface = (*MyType)(nil)
+```
+
 ### Concurrency
 
 Use goroutines and channels for concurrent programming:
@@ -178,6 +221,26 @@ For detailed information, consult the reference files:
    - Start comments with the name being described
    - Use godoc format
 
+6. **Configuration - CRITICAL**
+   - **NEVER** use `os.Getenv()` scattered throughout packages
+   - **ALWAYS** centralize environment variable parsing in a single config package (e.g., `app/config/`)
+   - Pass configuration via structs, not by reading environment directly
+   - This ensures discoverability, documentation, and testability of all config options
+
+7. **Constants - CRITICAL**
+   - **ALWAYS** define named constants for values used more than a few times
+   - **ALWAYS** define named constants if multiple packages depend on the same value
+   - Constants shared across packages belong in a dedicated package (e.g., `pkg/constants/`)
+   - Magic numbers and strings are forbidden
+   ```go
+   // BAD - magic number
+   if size > 1024 {
+
+   // GOOD - named constant
+   const MaxBufferSize = 1024
+   if size > MaxBufferSize {
+   ```
+
 ## Common Commands
 
 ```bash

.claude/skills/nostr-tools/SKILL.md

@@ -0,0 +1,767 @@
+---
+name: nostr-tools
+description: This skill should be used when working with nostr-tools library for Nostr protocol operations, including event creation, signing, filtering, relay communication, and NIP implementations. Provides comprehensive knowledge of nostr-tools APIs and patterns.
+---
+
+# nostr-tools Skill
+
+This skill provides comprehensive knowledge and patterns for working with nostr-tools, the most popular JavaScript/TypeScript library for Nostr protocol development.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building Nostr clients or applications
+- Creating and signing Nostr events
+- Connecting to Nostr relays
+- Implementing NIP features
+- Working with Nostr keys and cryptography
+- Filtering and querying events
+- Building relay pools or connections
+- Implementing NIP-44/NIP-04 encryption
+
+## Core Concepts
+
+### nostr-tools Overview
+
+nostr-tools provides:
+- **Event handling** - Create, sign, verify events
+- **Key management** - Generate, convert, encode keys
+- **Relay communication** - Connect, subscribe, publish
+- **NIP implementations** - NIP-04, NIP-05, NIP-19, NIP-44, etc.
+- **Cryptographic operations** - Schnorr signatures, encryption
+- **Filter building** - Query events by various criteria
+
+### Installation
+
+```bash
+npm install nostr-tools
+```
+
+### Basic Imports
+
+```javascript
+// Core functionality
+import {
+  SimplePool,
+  generateSecretKey,
+  getPublicKey,
+  finalizeEvent,
+  verifyEvent
+} from 'nostr-tools';
+
+// NIP-specific imports
+import { nip04, nip05, nip19, nip44 } from 'nostr-tools';
+
+// Relay operations
+import { Relay } from 'nostr-tools/relay';
+```
+
+## Key Management
+
+### Generating Keys
+
+```javascript
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+
+// Generate new secret key (Uint8Array)
+const secretKey = generateSecretKey();
+
+// Derive public key
+const publicKey = getPublicKey(secretKey);
+
+console.log('Secret key:', bytesToHex(secretKey));
+console.log('Public key:', publicKey); // hex string
+```
+
+### Key Encoding (NIP-19)
+
+```javascript
+import { nip19 } from 'nostr-tools';
+
+// Encode to bech32
+const nsec = nip19.nsecEncode(secretKey);
+const npub = nip19.npubEncode(publicKey);
+const note = nip19.noteEncode(eventId);
+
+console.log(nsec); // nsec1...
+console.log(npub); // npub1...
+console.log(note); // note1...
+
+// Decode from bech32
+const { type, data } = nip19.decode(npub);
+// type: 'npub', data: publicKey (hex)
+
+// Encode profile reference (nprofile)
+const nprofile = nip19.nprofileEncode({
+  pubkey: publicKey,
+  relays: ['wss://relay.example.com']
+});
+
+// Encode event reference (nevent)
+const nevent = nip19.neventEncode({
+  id: eventId,
+  relays: ['wss://relay.example.com'],
+  author: publicKey,
+  kind: 1
+});
+
+// Encode address (naddr) for replaceable events
+const naddr = nip19.naddrEncode({
+  identifier: 'my-article',
+  pubkey: publicKey,
+  kind: 30023,
+  relays: ['wss://relay.example.com']
+});
+```
+
+## Event Operations
+
+### Event Structure
+
+```javascript
+// Unsigned event template
+const eventTemplate = {
+  kind: 1,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  content: 'Hello Nostr!'
+};
+
+// Signed event (after finalizeEvent)
+const signedEvent = {
+  id: '...', // 32-byte sha256 hash as hex
+  pubkey: '...', // 32-byte public key as hex
+  created_at: 1234567890,
+  kind: 1,
+  tags: [],
+  content: 'Hello Nostr!',
+  sig: '...' // 64-byte Schnorr signature as hex
+};
+```
+
+### Creating and Signing Events
+
+```javascript
+import { finalizeEvent, verifyEvent } from 'nostr-tools/pure';
+
+// Create event template
+const eventTemplate = {
+  kind: 1,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [
+    ['p', publicKey], // Mention
+    ['e', eventId, '', 'reply'], // Reply
+    ['t', 'nostr'] // Hashtag
+  ],
+  content: 'Hello Nostr!'
+};
+
+// Sign event
+const signedEvent = finalizeEvent(eventTemplate, secretKey);
+
+// Verify event
+const isValid = verifyEvent(signedEvent);
+console.log('Event valid:', isValid);
+```
+
+### Event Kinds
+
+```javascript
+// Common event kinds
+const KINDS = {
+  Metadata: 0,           // Profile metadata (NIP-01)
+  Text: 1,               // Short text note (NIP-01)
+  RecommendRelay: 2,     // Relay recommendation
+  Contacts: 3,           // Contact list (NIP-02)
+  EncryptedDM: 4,        // Encrypted DM (NIP-04)
+  EventDeletion: 5,      // Delete events (NIP-09)
+  Repost: 6,             // Repost (NIP-18)
+  Reaction: 7,           // Reaction (NIP-25)
+  ChannelCreation: 40,   // Channel (NIP-28)
+  ChannelMessage: 42,    // Channel message
+  Zap: 9735,             // Zap receipt (NIP-57)
+  Report: 1984,          // Report (NIP-56)
+  RelayList: 10002,      // Relay list (NIP-65)
+  Article: 30023,        // Long-form content (NIP-23)
+};
+```
+
+### Creating Specific Events
+
+```javascript
+// Profile metadata (kind 0)
+const profileEvent = finalizeEvent({
+  kind: 0,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  content: JSON.stringify({
+    name: 'Alice',
+    about: 'Nostr enthusiast',
+    picture: 'https://example.com/avatar.jpg',
+    nip05: 'alice@example.com',
+    lud16: 'alice@getalby.com'
+  })
+}, secretKey);
+
+// Contact list (kind 3)
+const contactsEvent = finalizeEvent({
+  kind: 3,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [
+    ['p', pubkey1, 'wss://relay1.com', 'alice'],
+    ['p', pubkey2, 'wss://relay2.com', 'bob'],
+    ['p', pubkey3, '', 'carol']
+  ],
+  content: '' // Or JSON relay preferences
+}, secretKey);
+
+// Reply to an event
+const replyEvent = finalizeEvent({
+  kind: 1,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [
+    ['e', rootEventId, '', 'root'],
+    ['e', parentEventId, '', 'reply'],
+    ['p', parentEventPubkey]
+  ],
+  content: 'This is a reply'
+}, secretKey);
+
+// Reaction (kind 7)
+const reactionEvent = finalizeEvent({
+  kind: 7,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [
+    ['e', eventId],
+    ['p', eventPubkey]
+  ],
+  content: '+' // or '-' or emoji
+}, secretKey);
+
+// Delete event (kind 5)
+const deleteEvent = finalizeEvent({
+  kind: 5,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [
+    ['e', eventIdToDelete],
+    ['e', anotherEventIdToDelete]
+  ],
+  content: 'Deletion reason'
+}, secretKey);
+```
+
+## Relay Communication
+
+### Using SimplePool
+
+SimplePool is the recommended way to interact with multiple relays:
+
+```javascript
+import { SimplePool } from 'nostr-tools/pool';
+
+const pool = new SimplePool();
+const relays = [
+  'wss://relay.damus.io',
+  'wss://nos.lol',
+  'wss://relay.nostr.band'
+];
+
+// Subscribe to events
+const subscription = pool.subscribeMany(
+  relays,
+  [
+    {
+      kinds: [1],
+      authors: [publicKey],
+      limit: 10
+    }
+  ],
+  {
+    onevent(event) {
+      console.log('Received event:', event);
+    },
+    oneose() {
+      console.log('End of stored events');
+    }
+  }
+);
+
+// Close subscription when done
+subscription.close();
+
+// Publish event to all relays
+const results = await Promise.allSettled(
+  pool.publish(relays, signedEvent)
+);
+
+// Query events (returns Promise)
+const events = await pool.querySync(relays, {
+  kinds: [0],
+  authors: [publicKey]
+});
+
+// Get single event
+const event = await pool.get(relays, {
+  ids: [eventId]
+});
+
+// Close pool when done
+pool.close(relays);
+```
+
+### Direct Relay Connection
+
+```javascript
+import { Relay } from 'nostr-tools/relay';
+
+const relay = await Relay.connect('wss://relay.damus.io');
+
+console.log(`Connected to ${relay.url}`);
+
+// Subscribe
+const sub = relay.subscribe([
+  {
+    kinds: [1],
+    limit: 100
+  }
+], {
+  onevent(event) {
+    console.log('Event:', event);
+  },
+  oneose() {
+    console.log('EOSE');
+    sub.close();
+  }
+});
+
+// Publish
+await relay.publish(signedEvent);
+
+// Close
+relay.close();
+```
+
+### Handling Connection States
+
+```javascript
+import { Relay } from 'nostr-tools/relay';
+
+const relay = await Relay.connect('wss://relay.example.com');
+
+// Listen for disconnect
+relay.onclose = () => {
+  console.log('Relay disconnected');
+};
+
+// Check connection status
+console.log('Connected:', relay.connected);
+```
+
+## Filters
+
+### Filter Structure
+
+```javascript
+const filter = {
+  // Event IDs
+  ids: ['abc123...'],
+
+  // Authors (pubkeys)
+  authors: ['pubkey1', 'pubkey2'],
+
+  // Event kinds
+  kinds: [1, 6, 7],
+
+  // Tags (single-letter keys)
+  '#e': ['eventId1', 'eventId2'],
+  '#p': ['pubkey1'],
+  '#t': ['nostr', 'bitcoin'],
+  '#d': ['article-identifier'],
+
+  // Time range
+  since: 1704067200, // Unix timestamp
+  until: 1704153600,
+
+  // Limit results
+  limit: 100,
+
+  // Search (NIP-50, if relay supports)
+  search: 'nostr protocol'
+};
+```
+
+### Common Filter Patterns
+
+```javascript
+// User's recent posts
+const userPosts = {
+  kinds: [1],
+  authors: [userPubkey],
+  limit: 50
+};
+
+// User's profile
+const userProfile = {
+  kinds: [0],
+  authors: [userPubkey]
+};
+
+// User's contacts
+const userContacts = {
+  kinds: [3],
+  authors: [userPubkey]
+};
+
+// Replies to an event
+const replies = {
+  kinds: [1],
+  '#e': [eventId]
+};
+
+// Reactions to an event
+const reactions = {
+  kinds: [7],
+  '#e': [eventId]
+};
+
+// Feed from followed users
+const feed = {
+  kinds: [1, 6],
+  authors: followedPubkeys,
+  limit: 100
+};
+
+// Events mentioning user
+const mentions = {
+  kinds: [1],
+  '#p': [userPubkey],
+  limit: 50
+};
+
+// Hashtag search
+const hashtagEvents = {
+  kinds: [1],
+  '#t': ['bitcoin'],
+  limit: 100
+};
+
+// Replaceable event by d-tag
+const replaceableEvent = {
+  kinds: [30023],
+  authors: [authorPubkey],
+  '#d': ['article-slug']
+};
+```
+
+### Multiple Filters
+
+```javascript
+// Subscribe with multiple filters (OR logic)
+const filters = [
+  { kinds: [1], authors: [userPubkey], limit: 20 },
+  { kinds: [1], '#p': [userPubkey], limit: 20 }
+];
+
+pool.subscribeMany(relays, filters, {
+  onevent(event) {
+    // Receives events matching ANY filter
+  }
+});
+```
+
+## Encryption
+
+### NIP-04 (Legacy DMs)
+
+```javascript
+import { nip04 } from 'nostr-tools';
+
+// Encrypt message
+const ciphertext = await nip04.encrypt(
+  secretKey,
+  recipientPubkey,
+  'Hello, this is secret!'
+);
+
+// Create encrypted DM event
+const dmEvent = finalizeEvent({
+  kind: 4,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [['p', recipientPubkey]],
+  content: ciphertext
+}, secretKey);
+
+// Decrypt message
+const plaintext = await nip04.decrypt(
+  secretKey,
+  senderPubkey,
+  ciphertext
+);
+```
+
+### NIP-44 (Modern Encryption)
+
+```javascript
+import { nip44 } from 'nostr-tools';
+
+// Get conversation key (cache this for multiple messages)
+const conversationKey = nip44.getConversationKey(
+  secretKey,
+  recipientPubkey
+);
+
+// Encrypt
+const ciphertext = nip44.encrypt(
+  'Hello with NIP-44!',
+  conversationKey
+);
+
+// Decrypt
+const plaintext = nip44.decrypt(
+  ciphertext,
+  conversationKey
+);
+```
+
+## NIP Implementations
+
+### NIP-05 (DNS Identifier)
+
+```javascript
+import { nip05 } from 'nostr-tools';
+
+// Query NIP-05 identifier
+const profile = await nip05.queryProfile('alice@example.com');
+
+if (profile) {
+  console.log('Pubkey:', profile.pubkey);
+  console.log('Relays:', profile.relays);
+}
+
+// Verify NIP-05 for a pubkey
+const isValid = await nip05.queryProfile('alice@example.com')
+  .then(p => p?.pubkey === expectedPubkey);
+```
+
+### NIP-10 (Reply Threading)
+
+```javascript
+import { nip10 } from 'nostr-tools';
+
+// Parse reply tags
+const parsed = nip10.parse(event);
+
+console.log('Root:', parsed.root);     // Original event
+console.log('Reply:', parsed.reply);   // Direct parent
+console.log('Mentions:', parsed.mentions); // Other mentions
+console.log('Profiles:', parsed.profiles); // Mentioned pubkeys
+```
+
+### NIP-21 (nostr: URIs)
+
+```javascript
+// Parse nostr: URIs
+const uri = 'nostr:npub1...';
+const { type, data } = nip19.decode(uri.replace('nostr:', ''));
+```
+
+### NIP-27 (Content References)
+
+```javascript
+// Parse nostr:npub and nostr:note references in content
+const content = 'Check out nostr:npub1abc... and nostr:note1xyz...';
+
+const references = content.match(/nostr:(n[a-z]+1[a-z0-9]+)/g);
+references?.forEach(ref => {
+  const decoded = nip19.decode(ref.replace('nostr:', ''));
+  console.log(decoded.type, decoded.data);
+});
+```
+
+### NIP-57 (Zaps)
+
+```javascript
+import { nip57 } from 'nostr-tools';
+
+// Validate zap receipt
+const zapReceipt = await pool.get(relays, {
+  kinds: [9735],
+  '#e': [eventId]
+});
+
+const validatedZap = await nip57.validateZapRequest(zapReceipt);
+```
+
+## Utilities
+
+### Hex and Bytes Conversion
+
+```javascript
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+
+// Convert secret key to hex
+const secretKeyHex = bytesToHex(secretKey);
+
+// Convert hex back to bytes
+const secretKeyBytes = hexToBytes(secretKeyHex);
+```
+
+### Event ID Calculation
+
+```javascript
+import { getEventHash } from 'nostr-tools/pure';
+
+// Calculate event ID without signing
+const eventId = getEventHash(unsignedEvent);
+```
+
+### Signature Operations
+
+```javascript
+import {
+  getSignature,
+  verifyEvent
+} from 'nostr-tools/pure';
+
+// Sign event data
+const signature = getSignature(unsignedEvent, secretKey);
+
+// Verify complete event
+const isValid = verifyEvent(signedEvent);
+```
+
+## Best Practices
+
+### Connection Management
+
+1. **Use SimplePool** - Manages connections efficiently
+2. **Limit concurrent connections** - Don't connect to too many relays
+3. **Handle disconnections** - Implement reconnection logic
+4. **Close subscriptions** - Always close when done
+
+### Event Handling
+
+1. **Verify events** - Always verify signatures
+2. **Deduplicate** - Events may come from multiple relays
+3. **Handle replaceable events** - Latest by created_at wins
+4. **Validate content** - Don't trust event content blindly
+
+### Key Security
+
+1. **Never expose secret keys** - Keep in secure storage
+2. **Use NIP-07 in browsers** - Let extensions handle signing
+3. **Validate input** - Check key formats before use
+
+### Performance
+
+1. **Cache events** - Avoid re-fetching
+2. **Use filters wisely** - Be specific, use limits
+3. **Batch operations** - Combine related queries
+4. **Close idle connections** - Free up resources
+
+## Common Patterns
+
+### Building a Feed
+
+```javascript
+const pool = new SimplePool();
+const relays = ['wss://relay.damus.io', 'wss://nos.lol'];
+
+async function loadFeed(followedPubkeys) {
+  const events = await pool.querySync(relays, {
+    kinds: [1, 6],
+    authors: followedPubkeys,
+    limit: 100
+  });
+
+  // Sort by timestamp
+  return events.sort((a, b) => b.created_at - a.created_at);
+}
+```
+
+### Real-time Updates
+
+```javascript
+function subscribeToFeed(followedPubkeys, onEvent) {
+  return pool.subscribeMany(
+    relays,
+    [{ kinds: [1, 6], authors: followedPubkeys }],
+    {
+      onevent: onEvent,
+      oneose() {
+        console.log('Caught up with stored events');
+      }
+    }
+  );
+}
+```
+
+### Profile Loading
+
+```javascript
+async function loadProfile(pubkey) {
+  const [metadata] = await pool.querySync(relays, {
+    kinds: [0],
+    authors: [pubkey],
+    limit: 1
+  });
+
+  if (metadata) {
+    return JSON.parse(metadata.content);
+  }
+  return null;
+}
+```
+
+### Event Deduplication
+
+```javascript
+const seenEvents = new Set();
+
+function handleEvent(event) {
+  if (seenEvents.has(event.id)) {
+    return; // Skip duplicate
+  }
+  seenEvents.add(event.id);
+
+  // Process event...
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Events not publishing:**
+- Check relay is writable
+- Verify event is properly signed
+- Check relay's accepted kinds
+
+**Subscription not receiving events:**
+- Verify filter syntax
+- Check relay has matching events
+- Ensure subscription isn't closed
+
+**Signature verification fails:**
+- Check event structure is correct
+- Verify keys are in correct format
+- Ensure event hasn't been modified
+
+**NIP-05 lookup fails:**
+- Check CORS headers on server
+- Verify .well-known path is correct
+- Handle network timeouts
+
+## References
+
+- **nostr-tools GitHub**: https://github.com/nbd-wtf/nostr-tools
+- **Nostr Protocol**: https://github.com/nostr-protocol/nostr
+- **NIPs Repository**: https://github.com/nostr-protocol/nips
+- **NIP-01 (Basic Protocol)**: https://github.com/nostr-protocol/nips/blob/master/01.md
+
+## Related Skills
+
+- **nostr** - Nostr protocol fundamentals
+- **svelte** - Building Nostr UIs with Svelte
+- **applesauce-core** - Higher-level Nostr client utilities
+- **applesauce-signers** - Nostr signing abstractions

.claude/skills/nostr/SKILL.md

@@ -150,10 +150,20 @@ Event kind `7` for reactions:
 
 #### NIP-42: Authentication
 Client authentication to relays:
-- AUTH message from relay
-- Client responds with event kind `22242`
+- AUTH message from relay (challenge)
+- Client responds with event kind `22242` signed auth event
 - Proves key ownership
 
+**CRITICAL: Clients MUST wait for OK response after AUTH**
+- Relays MUST respond to AUTH with an OK message (same as EVENT)
+- An OK with `true` confirms the relay has stored the authenticated pubkey
+- An OK with `false` indicates authentication failed:
+  1. **Alert the user** that authentication failed
+  2. **Assume the relay will reject** subsequent events requiring auth
+  3. Check the `reason` field for error details (e.g., "error: failed to parse auth event")
+- Do NOT send events requiring authentication until OK `true` is received
+- If no OK is received within timeout, assume connection issues and retry or alert user
+
 #### NIP-50: Search
 Query filter extension for full-text search:
 - `search` field in REQ filters

.claude/skills/rollup/SKILL.md

@@ -0,0 +1,899 @@
+---
+name: rollup
+description: This skill should be used when working with Rollup module bundler, including configuration, plugins, code splitting, and build optimization. Provides comprehensive knowledge of Rollup patterns, plugin development, and bundling strategies.
+---
+
+# Rollup Skill
+
+This skill provides comprehensive knowledge and patterns for working with Rollup module bundler effectively.
+
+## When to Use This Skill
+
+Use this skill when:
+- Configuring Rollup for web applications
+- Setting up Rollup for library builds
+- Working with Rollup plugins
+- Implementing code splitting
+- Optimizing bundle size
+- Troubleshooting build issues
+- Integrating Rollup with Svelte or other frameworks
+- Developing custom Rollup plugins
+
+## Core Concepts
+
+### Rollup Overview
+
+Rollup is a module bundler that:
+- **Tree-shakes by default** - Removes unused code automatically
+- **ES module focused** - Native ESM output support
+- **Plugin-based** - Extensible architecture
+- **Multiple outputs** - Generate multiple formats from single input
+- **Code splitting** - Dynamic imports for lazy loading
+- **Scope hoisting** - Flattens modules for smaller bundles
+
+### Basic Configuration
+
+```javascript
+// rollup.config.js
+export default {
+  input: 'src/main.js',
+  output: {
+    file: 'dist/bundle.js',
+    format: 'esm'
+  }
+};
+```
+
+### Output Formats
+
+Rollup supports multiple output formats:
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `esm` | ES modules | Modern browsers, bundlers |
+| `cjs` | CommonJS | Node.js |
+| `iife` | Self-executing function | Script tags |
+| `umd` | Universal Module Definition | CDN, both environments |
+| `amd` | Asynchronous Module Definition | RequireJS |
+| `system` | SystemJS | SystemJS loader |
+
+## Configuration
+
+### Full Configuration Options
+
+```javascript
+// rollup.config.js
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import terser from '@rollup/plugin-terser';
+
+const production = !process.env.ROLLUP_WATCH;
+
+export default {
+  // Entry point(s)
+  input: 'src/main.js',
+
+  // Output configuration
+  output: {
+    // Output file or directory
+    file: 'dist/bundle.js',
+    // Or for code splitting:
+    // dir: 'dist',
+
+    // Output format
+    format: 'esm',
+
+    // Name for IIFE/UMD builds
+    name: 'MyBundle',
+
+    // Sourcemap generation
+    sourcemap: true,
+
+    // Global variables for external imports (IIFE/UMD)
+    globals: {
+      jquery: '$'
+    },
+
+    // Banner/footer comments
+    banner: '/* My library v1.0.0 */',
+    footer: '/* End of bundle */',
+
+    // Chunk naming for code splitting
+    chunkFileNames: '[name]-[hash].js',
+    entryFileNames: '[name].js',
+
+    // Manual chunks for code splitting
+    manualChunks: {
+      vendor: ['lodash', 'moment']
+    },
+
+    // Interop mode for default exports
+    interop: 'auto',
+
+    // Preserve modules structure
+    preserveModules: false,
+
+    // Exports mode
+    exports: 'auto' // 'default', 'named', 'none', 'auto'
+  },
+
+  // External dependencies (not bundled)
+  external: ['lodash', /^node:/],
+
+  // Plugin array
+  plugins: [
+    resolve({
+      browser: true,
+      dedupe: ['svelte']
+    }),
+    commonjs(),
+    production && terser()
+  ],
+
+  // Watch mode options
+  watch: {
+    include: 'src/**',
+    exclude: 'node_modules/**',
+    clearScreen: false
+  },
+
+  // Warning handling
+  onwarn(warning, warn) {
+    // Skip certain warnings
+    if (warning.code === 'CIRCULAR_DEPENDENCY') return;
+    warn(warning);
+  },
+
+  // Preserve entry signatures for code splitting
+  preserveEntrySignatures: 'strict',
+
+  // Treeshake options
+  treeshake: {
+    moduleSideEffects: false,
+    propertyReadSideEffects: false
+  }
+};
+```
+
+### Multiple Outputs
+
+```javascript
+export default {
+  input: 'src/main.js',
+  output: [
+    {
+      file: 'dist/bundle.esm.js',
+      format: 'esm'
+    },
+    {
+      file: 'dist/bundle.cjs.js',
+      format: 'cjs'
+    },
+    {
+      file: 'dist/bundle.umd.js',
+      format: 'umd',
+      name: 'MyLibrary'
+    }
+  ]
+};
+```
+
+### Multiple Entry Points
+
+```javascript
+export default {
+  input: {
+    main: 'src/main.js',
+    utils: 'src/utils.js'
+  },
+  output: {
+    dir: 'dist',
+    format: 'esm'
+  }
+};
+```
+
+### Array of Configurations
+
+```javascript
+export default [
+  {
+    input: 'src/main.js',
+    output: { file: 'dist/main.js', format: 'esm' }
+  },
+  {
+    input: 'src/worker.js',
+    output: { file: 'dist/worker.js', format: 'iife' }
+  }
+];
+```
+
+## Essential Plugins
+
+### @rollup/plugin-node-resolve
+
+Resolve node_modules imports:
+
+```javascript
+import resolve from '@rollup/plugin-node-resolve';
+
+export default {
+  plugins: [
+    resolve({
+      // Resolve browser field in package.json
+      browser: true,
+
+      // Prefer built-in modules
+      preferBuiltins: true,
+
+      // Only resolve these extensions
+      extensions: ['.mjs', '.js', '.json', '.node'],
+
+      // Dedupe packages (important for Svelte)
+      dedupe: ['svelte'],
+
+      // Main fields to check in package.json
+      mainFields: ['module', 'main', 'browser'],
+
+      // Export conditions
+      exportConditions: ['svelte', 'browser', 'module', 'import']
+    })
+  ]
+};
+```
+
+### @rollup/plugin-commonjs
+
+Convert CommonJS to ES modules:
+
+```javascript
+import commonjs from '@rollup/plugin-commonjs';
+
+export default {
+  plugins: [
+    commonjs({
+      // Include specific modules
+      include: /node_modules/,
+
+      // Exclude specific modules
+      exclude: ['node_modules/lodash-es/**'],
+
+      // Ignore conditional requires
+      ignoreDynamicRequires: false,
+
+      // Transform mixed ES/CJS modules
+      transformMixedEsModules: true,
+
+      // Named exports for specific modules
+      namedExports: {
+        'react': ['createElement', 'Component']
+      }
+    })
+  ]
+};
+```
+
+### @rollup/plugin-terser
+
+Minify output:
+
+```javascript
+import terser from '@rollup/plugin-terser';
+
+export default {
+  plugins: [
+    terser({
+      compress: {
+        drop_console: true,
+        drop_debugger: true
+      },
+      mangle: true,
+      format: {
+        comments: false
+      }
+    })
+  ]
+};
+```
+
+### rollup-plugin-svelte
+
+Compile Svelte components:
+
+```javascript
+import svelte from 'rollup-plugin-svelte';
+import css from 'rollup-plugin-css-only';
+
+export default {
+  plugins: [
+    svelte({
+      // Enable dev mode
+      dev: !production,
+
+      // Emit CSS as a separate file
+      emitCss: true,
+
+      // Preprocess (SCSS, TypeScript, etc.)
+      preprocess: sveltePreprocess(),
+
+      // Compiler options
+      compilerOptions: {
+        dev: !production
+      },
+
+      // Custom element mode
+      customElement: false
+    }),
+
+    // Extract CSS to separate file
+    css({ output: 'bundle.css' })
+  ]
+};
+```
+
+### Other Common Plugins
+
+```javascript
+import json from '@rollup/plugin-json';
+import replace from '@rollup/plugin-replace';
+import alias from '@rollup/plugin-alias';
+import image from '@rollup/plugin-image';
+import copy from 'rollup-plugin-copy';
+import livereload from 'rollup-plugin-livereload';
+
+export default {
+  plugins: [
+    // Import JSON files
+    json(),
+
+    // Replace strings in code
+    replace({
+      preventAssignment: true,
+      'process.env.NODE_ENV': JSON.stringify('production'),
+      '__VERSION__': JSON.stringify('1.0.0')
+    }),
+
+    // Path aliases
+    alias({
+      entries: [
+        { find: '@', replacement: './src' },
+        { find: 'utils', replacement: './src/utils' }
+      ]
+    }),
+
+    // Import images
+    image(),
+
+    // Copy static files
+    copy({
+      targets: [
+        { src: 'public/*', dest: 'dist' }
+      ]
+    }),
+
+    // Live reload in dev
+    !production && livereload('dist')
+  ]
+};
+```
+
+## Code Splitting
+
+### Dynamic Imports
+
+```javascript
+// Automatically creates chunks
+async function loadFeature() {
+  const { feature } = await import('./feature.js');
+  feature();
+}
+```
+
+Configuration for code splitting:
+
+```javascript
+export default {
+  input: 'src/main.js',
+  output: {
+    dir: 'dist',
+    format: 'esm',
+    chunkFileNames: 'chunks/[name]-[hash].js'
+  }
+};
+```
+
+### Manual Chunks
+
+```javascript
+export default {
+  output: {
+    manualChunks: {
+      // Vendor chunk
+      vendor: ['lodash', 'moment'],
+
+      // Or use a function for more control
+      manualChunks(id) {
+        if (id.includes('node_modules')) {
+          return 'vendor';
+        }
+      }
+    }
+  }
+};
+```
+
+### Advanced Chunking Strategy
+
+```javascript
+export default {
+  output: {
+    manualChunks(id, { getModuleInfo }) {
+      // Separate chunks by feature
+      if (id.includes('/features/auth/')) {
+        return 'auth';
+      }
+      if (id.includes('/features/dashboard/')) {
+        return 'dashboard';
+      }
+
+      // Vendor chunks by package
+      if (id.includes('node_modules')) {
+        const match = id.match(/node_modules\/([^/]+)/);
+        if (match) {
+          const packageName = match[1];
+          // Group small packages
+          const smallPackages = ['lodash', 'date-fns'];
+          if (smallPackages.includes(packageName)) {
+            return 'vendor-utils';
+          }
+          return `vendor-${packageName}`;
+        }
+      }
+    }
+  }
+};
+```
+
+## Watch Mode
+
+### Configuration
+
+```javascript
+export default {
+  watch: {
+    // Files to watch
+    include: 'src/**',
+
+    // Files to ignore
+    exclude: 'node_modules/**',
+
+    // Don't clear screen on rebuild
+    clearScreen: false,
+
+    // Rebuild delay
+    buildDelay: 0,
+
+    // Watch chokidar options
+    chokidar: {
+      usePolling: true
+    }
+  }
+};
+```
+
+### CLI Watch Mode
+
+```bash
+# Watch mode
+rollup -c -w
+
+# With environment variable
+ROLLUP_WATCH=true rollup -c
+```
+
+## Plugin Development
+
+### Plugin Structure
+
+```javascript
+function myPlugin(options = {}) {
+  return {
+    // Plugin name (required)
+    name: 'my-plugin',
+
+    // Build hooks
+    options(inputOptions) {
+      // Modify input options
+      return inputOptions;
+    },
+
+    buildStart(inputOptions) {
+      // Called on build start
+    },
+
+    resolveId(source, importer, options) {
+      // Custom module resolution
+      if (source === 'virtual-module') {
+        return source;
+      }
+      return null; // Defer to other plugins
+    },
+
+    load(id) {
+      // Load module content
+      if (id === 'virtual-module') {
+        return 'export default "Hello"';
+      }
+      return null;
+    },
+
+    transform(code, id) {
+      // Transform module code
+      if (id.endsWith('.txt')) {
+        return {
+          code: `export default ${JSON.stringify(code)}`,
+          map: null
+        };
+      }
+    },
+
+    buildEnd(error) {
+      // Called when build ends
+      if (error) {
+        console.error('Build failed:', error);
+      }
+    },
+
+    // Output generation hooks
+    renderStart(outputOptions, inputOptions) {
+      // Called before output generation
+    },
+
+    banner() {
+      return '/* Custom banner */';
+    },
+
+    footer() {
+      return '/* Custom footer */';
+    },
+
+    renderChunk(code, chunk, options) {
+      // Transform output chunk
+      return code;
+    },
+
+    generateBundle(options, bundle) {
+      // Modify output bundle
+      for (const fileName in bundle) {
+        const chunk = bundle[fileName];
+        if (chunk.type === 'chunk') {
+          // Modify chunk
+        }
+      }
+    },
+
+    writeBundle(options, bundle) {
+      // After bundle is written
+    },
+
+    closeBundle() {
+      // Called when bundle is closed
+    }
+  };
+}
+
+export default myPlugin;
+```
+
+### Plugin with Rollup Utils
+
+```javascript
+import { createFilter } from '@rollup/pluginutils';
+
+function myTransformPlugin(options = {}) {
+  const filter = createFilter(options.include, options.exclude);
+
+  return {
+    name: 'my-transform',
+
+    transform(code, id) {
+      if (!filter(id)) return null;
+
+      // Transform code
+      const transformed = code.replace(/foo/g, 'bar');
+
+      return {
+        code: transformed,
+        map: null // Or generate sourcemap
+      };
+    }
+  };
+}
+```
+
+## Svelte Integration
+
+### Complete Svelte Setup
+
+```javascript
+// rollup.config.js
+import svelte from 'rollup-plugin-svelte';
+import commonjs from '@rollup/plugin-commonjs';
+import resolve from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+import css from 'rollup-plugin-css-only';
+import livereload from 'rollup-plugin-livereload';
+
+const production = !process.env.ROLLUP_WATCH;
+
+function serve() {
+  let server;
+
+  function toExit() {
+    if (server) server.kill(0);
+  }
+
+  return {
+    writeBundle() {
+      if (server) return;
+      server = require('child_process').spawn(
+        'npm',
+        ['run', 'start', '--', '--dev'],
+        {
+          stdio: ['ignore', 'inherit', 'inherit'],
+          shell: true
+        }
+      );
+
+      process.on('SIGTERM', toExit);
+      process.on('exit', toExit);
+    }
+  };
+}
+
+export default {
+  input: 'src/main.js',
+  output: {
+    sourcemap: true,
+    format: 'iife',
+    name: 'app',
+    file: 'public/build/bundle.js'
+  },
+  plugins: [
+    svelte({
+      compilerOptions: {
+        dev: !production
+      }
+    }),
+    css({ output: 'bundle.css' }),
+
+    resolve({
+      browser: true,
+      dedupe: ['svelte']
+    }),
+    commonjs(),
+
+    // Dev server
+    !production && serve(),
+    !production && livereload('public'),
+
+    // Minify in production
+    production && terser()
+  ],
+  watch: {
+    clearScreen: false
+  }
+};
+```
+
+## Best Practices
+
+### Bundle Optimization
+
+1. **Enable tree shaking** - Use ES modules
+2. **Mark side effects** - Set `sideEffects` in package.json
+3. **Use terser** - Minify production builds
+4. **Analyze bundles** - Use rollup-plugin-visualizer
+5. **Code split** - Lazy load routes and features
+
+### External Dependencies
+
+```javascript
+export default {
+  // Don't bundle peer dependencies for libraries
+  external: [
+    'react',
+    'react-dom',
+    /^lodash\//
+  ],
+  output: {
+    globals: {
+      react: 'React',
+      'react-dom': 'ReactDOM'
+    }
+  }
+};
+```
+
+### Development vs Production
+
+```javascript
+const production = !process.env.ROLLUP_WATCH;
+
+export default {
+  plugins: [
+    replace({
+      preventAssignment: true,
+      'process.env.NODE_ENV': JSON.stringify(
+        production ? 'production' : 'development'
+      )
+    }),
+    production && terser()
+  ].filter(Boolean)
+};
+```
+
+### Error Handling
+
+```javascript
+export default {
+  onwarn(warning, warn) {
+    // Ignore circular dependency warnings
+    if (warning.code === 'CIRCULAR_DEPENDENCY') {
+      return;
+    }
+
+    // Ignore unused external imports
+    if (warning.code === 'UNUSED_EXTERNAL_IMPORT') {
+      return;
+    }
+
+    // Treat other warnings as errors
+    if (warning.code === 'UNRESOLVED_IMPORT') {
+      throw new Error(warning.message);
+    }
+
+    // Use default warning handling
+    warn(warning);
+  }
+};
+```
+
+## Common Patterns
+
+### Library Build
+
+```javascript
+import pkg from './package.json';
+
+export default {
+  input: 'src/index.js',
+  external: Object.keys(pkg.peerDependencies || {}),
+  output: [
+    {
+      file: pkg.main,
+      format: 'cjs',
+      sourcemap: true
+    },
+    {
+      file: pkg.module,
+      format: 'esm',
+      sourcemap: true
+    }
+  ]
+};
+```
+
+### Application Build
+
+```javascript
+export default {
+  input: 'src/main.js',
+  output: {
+    dir: 'dist',
+    format: 'esm',
+    chunkFileNames: 'chunks/[name]-[hash].js',
+    entryFileNames: '[name]-[hash].js',
+    sourcemap: true
+  },
+  plugins: [
+    // All dependencies bundled
+    resolve({ browser: true }),
+    commonjs(),
+    terser()
+  ]
+};
+```
+
+### Web Worker Build
+
+```javascript
+export default [
+  // Main application
+  {
+    input: 'src/main.js',
+    output: {
+      file: 'dist/main.js',
+      format: 'esm'
+    },
+    plugins: [resolve(), commonjs()]
+  },
+  // Web worker (IIFE format)
+  {
+    input: 'src/worker.js',
+    output: {
+      file: 'dist/worker.js',
+      format: 'iife'
+    },
+    plugins: [resolve(), commonjs()]
+  }
+];
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Module not found:**
+- Check @rollup/plugin-node-resolve is configured
+- Verify package is installed
+- Check `external` array
+
+**CommonJS module issues:**
+- Add @rollup/plugin-commonjs
+- Check `namedExports` configuration
+- Try `transformMixedEsModules: true`
+
+**Circular dependencies:**
+- Use `onwarn` to suppress or fix
+- Refactor to break cycles
+- Check import order
+
+**Sourcemaps not working:**
+- Set `sourcemap: true` in output
+- Ensure plugins pass through maps
+- Check browser devtools settings
+
+**Large bundle size:**
+- Use rollup-plugin-visualizer
+- Check for duplicate dependencies
+- Verify tree shaking is working
+- Mark unused packages as external
+
+## CLI Reference
+
+```bash
+# Basic build
+rollup -c
+
+# Watch mode
+rollup -c -w
+
+# Custom config
+rollup -c rollup.custom.config.js
+
+# Output format
+rollup src/main.js --format esm --file dist/bundle.js
+
+# Environment variables
+NODE_ENV=production rollup -c
+
+# Silent mode
+rollup -c --silent
+
+# Generate bundle stats
+rollup -c --perf
+```
+
+## References
+
+- **Rollup Documentation**: https://rollupjs.org
+- **Plugin Directory**: https://github.com/rollup/plugins
+- **Awesome Rollup**: https://github.com/rollup/awesome
+- **GitHub**: https://github.com/rollup/rollup
+
+## Related Skills
+
+- **svelte** - Using Rollup with Svelte
+- **typescript** - TypeScript compilation with Rollup
+- **nostr-tools** - Bundling Nostr applications

.dockerignore

@@ -0,0 +1,91 @@
+# Build artifacts
+orly
+test-build
+*.exe
+*.dll
+*.so
+!libsecp256k1.so
+*.dylib
+
+# Test files
+*_test.go
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Docker files (except the one we're using)
+Dockerfile*
+!scripts/Dockerfile.deploy-test
+docker-compose.yml
+.dockerignore
+
+# Node modules (will be installed during build)
+app/web/node_modules/
+# app/web/dist/ - NEEDED for embedded web UI
+app/web/bun.lockb
+
+# Go modules cache
+# go.sum - NEEDED for docker builds
+
+# Logs and temp files
+*.log
+tmp/
+temp/
+
+# Database files
+*.db
+*.badger
+
+# Certificates and keys
+*.pem
+*.key
+*.crt
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# Documentation that's not needed for deployment test
+docs/
+*.md
+*.adoc
+!README.adoc
+
+# Scripts we don't need for testing
+scripts/benchmark.sh
+scripts/reload.sh
+scripts/run-*.sh
+scripts/test.sh
+scripts/runtests.sh
+scripts/sprocket/
+
+# Benchmark and test data
+# cmd/benchmark/ - NEEDED for benchmark-runner docker build
+cmd/benchmark/data/
+cmd/benchmark/reports/
+cmd/benchmark/external/
+reports/
+*.txt
+*.conf
+*.jsonl
+
+# Policy test files
+POLICY_*.md
+test_policy.sh
+test-*.sh
+
+# Other build artifacts
+tee

.gitea/README.md

@@ -0,0 +1,84 @@
+# Gitea Actions Setup
+
+This directory contains workflows for Gitea Actions, which is a self-hosted CI/CD system compatible with GitHub Actions syntax.
+
+## Workflow: go.yml
+
+The `go.yml` workflow handles building, testing, and releasing the ORLY relay when version tags are pushed.
+
+### Features
+
+- **No external dependencies**: Uses only inline shell commands (no actions from GitHub)
+- **Pure Go builds**: Uses CGO_ENABLED=0 with purego for secp256k1
+- **Automated releases**: Creates Gitea releases with binaries and checksums
+- **Tests included**: Runs the full test suite before building releases
+
+### Prerequisites
+
+1. **Gitea Token**: Add a secret named `GITEA_TOKEN` in your repository settings
+   - Go to: Repository Settings → Secrets → Add Secret
+   - Name: `GITEA_TOKEN`
+   - Value: Your Gitea personal access token with `repo` and `write:packages` permissions
+
+2. **Runner Configuration**: Ensure your Gitea Actions runner is properly configured
+   - The runner should have access to pull Docker images
+   - Ubuntu-latest image should be available
+
+### Usage
+
+To create a new release:
+
+```bash
+# 1. Update version in pkg/version/version file
+echo "v0.29.4" > pkg/version/version
+
+# 2. Commit the version change
+git add pkg/version/version
+git commit -m "bump to v0.29.4"
+
+# 3. Create and push the tag
+git tag v0.29.4
+git push origin v0.29.4
+
+# 4. The workflow will automatically:
+#    - Build the binary
+#    - Run tests
+#    - Create a release on your Gitea instance
+#    - Upload the binary and checksums
+```
+
+### Environment Variables
+
+The workflow uses standard Gitea Actions environment variables:
+
+- `GITHUB_WORKSPACE`: Working directory for the job
+- `GITHUB_REF_NAME`: Tag name (e.g., v1.2.3)
+- `GITHUB_REPOSITORY`: Repository in format `owner/repo`
+- `GITHUB_SERVER_URL`: Your Gitea instance URL (e.g., https://git.nostrdev.com)
+
+### Troubleshooting
+
+**Issue**: Workflow fails to clone repository
+- **Solution**: Check that the repository is accessible without authentication, or configure runner credentials
+
+**Issue**: Cannot create release
+- **Solution**: Verify `GITEA_TOKEN` secret is set correctly with appropriate permissions
+
+**Issue**: Go version not found
+- **Solution**: The workflow downloads Go 1.25.3 directly from go.dev, ensure the runner has internet access
+
+### Customization
+
+To modify the workflow:
+
+1. Edit `.gitea/workflows/go.yml`
+2. Test changes by pushing a tag (or use `act` locally for testing)
+3. Monitor the Actions tab in your Gitea repository for results
+
+## Differences from GitHub Actions
+
+- **Action dependencies**: This workflow doesn't use external actions (like `actions/checkout@v4`) to avoid GitHub dependency
+- **Release creation**: Uses `tea` CLI instead of GitHub's release action
+- **Inline commands**: All setup and build steps are done with shell scripts
+
+This makes the workflow completely self-contained and independent of external services.

.gitea/issue_template/bug_report.yaml

@@ -0,0 +1,118 @@
+name: Bug Report
+about: Report a bug or unexpected behavior in ORLY relay
+title: "[BUG] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Bug Report Guidelines
+
+        Thank you for taking the time to report a bug. Please fill out the form below to help us understand and reproduce the issue.
+
+        **Before submitting:**
+        - Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates
+        - Check the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration guidance
+        - Ensure you're running a recent version of ORLY
+
+  - type: input
+    id: version
+    attributes:
+      label: ORLY Version
+      description: Run `./orly version` to get the version
+      placeholder: "v0.35.4"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: database
+    attributes:
+      label: Database Backend
+      description: Which database backend are you using?
+      options:
+        - Badger (default)
+        - Neo4j
+        - WasmDB
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug
+      placeholder: Describe what happened and what you expected to happen
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Detailed steps to reproduce the behavior
+      placeholder: |
+        1. Start relay with `./orly`
+        2. Connect with client X
+        3. Perform action Y
+        4. Observe error Z
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: |
+        Include relevant log output. Set `ORLY_LOG_LEVEL=debug` or `trace` for more detail.
+        This will be automatically formatted as code.
+      render: shell
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Configuration
+      description: |
+        Relevant environment variables or configuration (redact sensitive values).
+        This will be automatically formatted as code.
+      render: shell
+      placeholder: |
+        ORLY_ACL_MODE=follows
+        ORLY_POLICY_ENABLED=true
+        ORLY_DB_TYPE=badger
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating system, Go version, etc.
+      placeholder: |
+        OS: Linux 6.8.0
+        Go: 1.25.3
+        Architecture: amd64
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or information that might help
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues and this is not a duplicate
+          required: true
+        - label: I have included version information
+          required: true
+        - label: I have included steps to reproduce the issue
+          required: true

.gitea/issue_template/config.yaml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://git.mleku.dev/mleku/next.orly.dev
+    about: Check the repository documentation before opening an issue
+  - name: Nostr Protocol (NIPs)
+    url: https://github.com/nostr-protocol/nips
+    about: For questions about Nostr protocol specifications

.gitea/issue_template/feature_request.yaml

@@ -0,0 +1,118 @@
+name: Feature Request
+about: Suggest a new feature or enhancement for ORLY relay
+title: "[FEATURE] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Feature Request Guidelines
+
+        Thank you for suggesting a feature. Please provide as much detail as possible to help us understand your proposal.
+
+        **Before submitting:**
+        - Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates
+        - Check if this is covered by an existing [NIP](https://github.com/nostr-protocol/nips)
+        - Review the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for current capabilities
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Feature Category
+      description: What area of ORLY does this feature relate to?
+      options:
+        - Protocol (NIP implementation)
+        - Database / Storage
+        - Performance / Optimization
+        - Policy / Access Control
+        - Web UI / Admin Interface
+        - Deployment / Operations
+        - API / Integration
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: |
+        What problem does this feature solve? Is this related to a frustration you have?
+        A clear problem statement helps us understand the motivation.
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: |
+        Describe the solution you'd like. Be specific about expected behavior.
+      placeholder: "I would like ORLY to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: |
+        Describe any alternative solutions or workarounds you've considered.
+      placeholder: "I've tried X but it doesn't work because..."
+
+  - type: input
+    id: nip
+    attributes:
+      label: Related NIP
+      description: If this relates to a Nostr Implementation Possibility, provide the NIP number
+      placeholder: "NIP-XX"
+
+  - type: dropdown
+    id: impact
+    attributes:
+      label: Scope of Impact
+      description: How significant is this feature?
+      options:
+        - Minor enhancement (small quality-of-life improvement)
+        - Moderate feature (adds useful capability)
+        - Major feature (significant new functionality)
+        - Breaking change (requires migration or config changes)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: contribution
+    attributes:
+      label: Willingness to Contribute
+      description: Would you be willing to help implement this feature?
+      options:
+        - "Yes, I can submit a PR"
+        - "Yes, I can help with testing"
+        - "No, but I can provide more details"
+        - "No"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: |
+        Any other context, mockups, examples, or references that help explain the feature.
+
+        For protocol features, include example event structures or message flows if applicable.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues and this is not a duplicate
+          required: true
+        - label: I have described the problem this feature solves
+          required: true
+        - label: I have checked if this relates to an existing NIP
+          required: false

.gitea/workflows/go.yml

@@ -0,0 +1,204 @@
+# This workflow will build a golang project for Gitea Actions
+# Using inline commands to avoid external action dependencies
+#
+# NOTE: All builds use CGO_ENABLED=0 since p8k library uses purego (not CGO)
+#       The library dynamically loads libsecp256k1 at runtime via purego
+#
+# Release Process:
+# 1. Update the version in the pkg/version/version file (e.g. v1.2.3)
+# 2. Create and push a tag matching the version:
+#    git tag v1.2.3
+#    git push origin v1.2.3
+# 3. The workflow will automatically:
+#    - Build binaries for Linux AMD64
+#    - Run tests
+#    - Create a Gitea release with the binaries
+#    - Generate checksums
+
+name: Go
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        run: |
+          set -e
+          echo "Cloning repository..."
+          echo "GITHUB_REF_NAME=${GITHUB_REF_NAME}"
+          echo "GITHUB_SERVER_URL=${GITHUB_SERVER_URL}"
+          echo "GITHUB_REPOSITORY=${GITHUB_REPOSITORY}"
+          echo "GITHUB_WORKSPACE=${GITHUB_WORKSPACE}"
+          git clone --depth 1 --branch ${GITHUB_REF_NAME} ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git ${GITHUB_WORKSPACE}
+          cd ${GITHUB_WORKSPACE}
+          echo "Cloned successfully. Last commit:"
+          git log -1
+          ls -la
+
+      - name: Set up Go
+        run: |
+          set -e
+          echo "Setting up Go 1.25.3..."
+          cd /tmp
+          wget -q https://go.dev/dl/go1.25.3.linux-amd64.tar.gz
+          sudo rm -rf /usr/local/go
+          sudo tar -C /usr/local -xzf go1.25.3.linux-amd64.tar.gz
+          export PATH=/usr/local/go/bin:$PATH
+          go version
+
+      - name: Set up Bun
+        run: |
+          set -e
+          echo "Installing Bun..."
+          curl -fsSL https://bun.sh/install | bash
+          export BUN_INSTALL="$HOME/.bun"
+          export PATH="$BUN_INSTALL/bin:$PATH"
+          bun --version
+
+      - name: Build Web UI
+        run: |
+          set -e
+          export BUN_INSTALL="$HOME/.bun"
+          export PATH="$BUN_INSTALL/bin:$PATH"
+          cd ${GITHUB_WORKSPACE}/app/web
+          echo "Installing frontend dependencies..."
+          bun install
+          echo "Building web app..."
+          bun run build
+          echo "Verifying dist directory was created..."
+          ls -lah dist/
+          echo "Web UI build complete"
+
+      - name: Build (Pure Go + purego)
+        run: |
+          set -e
+          export PATH=/usr/local/go/bin:$PATH
+          cd ${GITHUB_WORKSPACE}
+          echo "Building with CGO_ENABLED=0..."
+          CGO_ENABLED=0 go build -v ./...
+
+      - name: Test (Pure Go + purego)
+        run: |
+          set -e
+          export PATH=/usr/local/go/bin:$PATH
+          cd ${GITHUB_WORKSPACE}
+          echo "Running tests..."
+          # libsecp256k1.so is included in the repository
+          chmod +x libsecp256k1.so
+          # Set LD_LIBRARY_PATH so tests can find the library
+          export LD_LIBRARY_PATH=${GITHUB_WORKSPACE}:${LD_LIBRARY_PATH}
+          # Run tests but don't fail the build on test failures (some tests may need specific env)
+          CGO_ENABLED=0 go test -v $(go list ./... | grep -v '/cmd/benchmark/external/' | xargs -n1 sh -c 'ls $0/*_test.go 1>/dev/null 2>&1 && echo $0' | grep .) || echo "Some tests failed, continuing..."
+
+      - name: Build Release Binaries (Pure Go + purego)
+        run: |
+          set -e
+          export PATH=/usr/local/go/bin:$PATH
+          cd ${GITHUB_WORKSPACE}
+
+          # Extract version from tag (e.g., v1.2.3 -> 1.2.3)
+          VERSION=${GITHUB_REF_NAME#v}
+          echo "Building release binaries for version $VERSION (pure Go + purego)"
+
+          # Create directory for binaries
+          mkdir -p release-binaries
+
+          # Copy libsecp256k1.so from repository to release binaries
+          cp libsecp256k1.so release-binaries/libsecp256k1-linux-amd64.so
+          chmod +x release-binaries/libsecp256k1-linux-amd64.so
+
+          # Build for Linux AMD64 (pure Go + purego dynamic loading)
+          echo "Building Linux AMD64 (pure Go + purego dynamic loading)..."
+          GOEXPERIMENT=greenteagc,jsonv2 GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
+            go build -ldflags "-s -w" -o release-binaries/orly-${VERSION}-linux-amd64 .
+
+          # Create checksums
+          cd release-binaries
+          sha256sum * > SHA256SUMS.txt
+          cat SHA256SUMS.txt
+          cd ..
+
+          echo "Release binaries built successfully:"
+          ls -lh release-binaries/
+
+      - name: Create Gitea Release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          set -e  # Exit on any error
+          export PATH=/usr/local/go/bin:$PATH
+          cd ${GITHUB_WORKSPACE}
+
+          # Validate GITEA_TOKEN is set
+          if [ -z "${GITEA_TOKEN}" ]; then
+            echo "ERROR: GITEA_TOKEN secret is not set!"
+            echo "Please configure the GITEA_TOKEN secret in repository settings."
+            exit 1
+          fi
+
+          VERSION=${GITHUB_REF_NAME}
+          REPO_OWNER=$(echo ${GITHUB_REPOSITORY} | cut -d'/' -f1)
+          REPO_NAME=$(echo ${GITHUB_REPOSITORY} | cut -d'/' -f2)
+
+          echo "Creating release for ${REPO_OWNER}/${REPO_NAME} version ${VERSION}"
+
+          # Verify release binaries exist
+          if [ ! -f "release-binaries/orly-${VERSION#v}-linux-amd64" ]; then
+            echo "ERROR: Release binary not found!"
+            ls -la release-binaries/ || echo "release-binaries directory does not exist"
+            exit 1
+          fi
+
+          # Use Gitea API directly (more reliable than tea CLI)
+          cd ${GITHUB_WORKSPACE}
+
+          API_URL="${GITHUB_SERVER_URL}/api/v1"
+
+          echo "Creating release via Gitea API..."
+          echo "API URL: ${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/releases"
+
+          # Create the release
+          RELEASE_RESPONSE=$(curl -s -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\": \"${VERSION}\", \"name\": \"Release ${VERSION}\", \"body\": \"Automated release ${VERSION}\"}" \
+            "${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/releases")
+
+          echo "Release response: ${RELEASE_RESPONSE}"
+
+          # Extract release ID
+          RELEASE_ID=$(echo "${RELEASE_RESPONSE}" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
+
+          if [ -z "${RELEASE_ID}" ]; then
+            echo "ERROR: Failed to create release or extract release ID"
+            echo "Full response: ${RELEASE_RESPONSE}"
+            exit 1
+          fi
+
+          echo "Release created with ID: ${RELEASE_ID}"
+
+          # Upload assets
+          for ASSET in release-binaries/orly-${VERSION#v}-linux-amd64 release-binaries/libsecp256k1-linux-amd64.so release-binaries/SHA256SUMS.txt; do
+            FILENAME=$(basename "${ASSET}")
+            echo "Uploading ${FILENAME}..."
+
+            UPLOAD_RESPONSE=$(curl -s -X POST \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -F "attachment=@${ASSET}" \
+              "${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/releases/${RELEASE_ID}/assets?name=${FILENAME}")
+
+            echo "Upload response for ${FILENAME}: ${UPLOAD_RESPONSE}"
+          done
+
+          echo "Release ${VERSION} created successfully with all assets!"
+
+          # Verify release exists
+          VERIFY=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" \
+            "${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/releases/tags/${VERSION}")
+          echo "Verification: ${VERIFY}" | head -c 500
+

.github/workflows/ci.yaml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Download libsecp256k1
+        run: |
+          wget -q https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/libsecp256k1.so -O libsecp256k1.so
+          chmod +x libsecp256k1.so
+
+      - name: Run tests
+        run: |
+          export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$(pwd)"
+          CGO_ENABLED=0 go test ./...
+
+      - name: Build binary
+        run: |
+          CGO_ENABLED=0 go build -o orly .
+          ./orly version
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Check go mod tidy
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+
+      - name: Run go vet
+        run: CGO_ENABLED=0 go vet ./...

.github/workflows/go.yml

@@ -1,88 +0,0 @@
-# This workflow will build a golang project
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
-#
-# NOTE: All builds use CGO_ENABLED=0 since p8k library uses purego (not CGO)
-#       The library dynamically loads libsecp256k1 at runtime via purego
-#
-# Release Process:
-# 1. Update the version in the pkg/version/version file (e.g. v1.2.3)
-# 2. Create and push a tag matching the version:
-#    git tag v1.2.3
-#    git push origin v1.2.3
-# 3. The workflow will automatically:
-#    - Build binaries for multiple platforms (Linux, macOS, Windows)
-#    - Create a GitHub release with the binaries
-#    - Generate release notes
-
-name: Go
-
-on:
-  push:
-    tags:
-      - "v[0-9]+.[0-9]+.[0-9]+"
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v4
-        with:
-          go-version: "1.25"
-
-      - name: Build (Pure Go + purego)
-        run: CGO_ENABLED=0 go build -v ./...
-
-      - name: Test (Pure Go + purego)
-        run: |
-          # Copy the libsecp256k1.so to root directory so tests can find it
-          cp pkg/crypto/p8k/libsecp256k1.so .
-          CGO_ENABLED=0 go test -v $(go list ./... | xargs -n1 sh -c 'ls $0/*_test.go 1>/dev/null 2>&1 && echo $0' | grep .)
-  release:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      packages: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v4
-        with:
-          go-version: '1.25'
-
-      - name: Build Release Binaries (Pure Go + purego)
-        if: startsWith(github.ref, 'refs/tags/v')
-        run: |
-          # Extract version from tag (e.g., v1.2.3 -> 1.2.3)
-          VERSION=${GITHUB_REF#refs/tags/v}
-          echo "Building release binaries for version $VERSION (pure Go + purego)"
-
-          # Create directory for binaries
-          mkdir -p release-binaries
-
-          # Copy the pre-compiled libsecp256k1.so for Linux AMD64
-          cp pkg/crypto/p8k/libsecp256k1.so release-binaries/libsecp256k1-linux-amd64.so
-
-          # Build for Linux AMD64 (pure Go + purego dynamic loading)
-          echo "Building Linux AMD64 (pure Go + purego dynamic loading)..."
-          GOEXPERIMENT=greenteagc,jsonv2 GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
-            go build -ldflags "-s -w" -o release-binaries/orly-${VERSION}-linux-amd64 .
-          
-          # Create checksums
-          cd release-binaries
-          sha256sum * > SHA256SUMS.txt
-          cd ..
-
-      - name: Create GitHub Release
-        if: startsWith(github.ref, 'refs/tags/v')
-        uses: softprops/action-gh-release@v1
-        with:
-          files: release-binaries/*
-          draft: false
-          prerelease: false
-          generate_release_notes: true

.github/workflows/release.yaml

@@ -0,0 +1,154 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            platform: linux-amd64
+            ext: ""
+            lib: libsecp256k1.so
+          - goos: linux
+            goarch: arm64
+            platform: linux-arm64
+            ext: ""
+            lib: libsecp256k1.so
+          - goos: darwin
+            goarch: amd64
+            platform: darwin-amd64
+            ext: ""
+            lib: libsecp256k1.dylib
+          - goos: darwin
+            goarch: arm64
+            platform: darwin-arm64
+            ext: ""
+            lib: libsecp256k1.dylib
+          - goos: windows
+            goarch: amd64
+            platform: windows-amd64
+            ext: ".exe"
+            lib: libsecp256k1.dll
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install bun
+        run: |
+          curl -fsSL https://bun.sh/install | bash
+          echo "$HOME/.bun/bin" >> $GITHUB_PATH
+
+      - name: Build Web UI
+        run: |
+          cd app/web
+          $HOME/.bun/bin/bun install
+          $HOME/.bun/bin/bun run build
+
+      - name: Get version
+        id: version
+        run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT
+
+      - name: Build binary
+        env:
+          CGO_ENABLED: 0
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          OUTPUT="orly-${VERSION}-${{ matrix.platform }}${{ matrix.ext }}"
+          go build -ldflags "-s -w -X main.version=${VERSION}" -o ${OUTPUT} .
+          sha256sum ${OUTPUT} > ${OUTPUT}.sha256
+
+      - name: Download runtime library
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          LIB="${{ matrix.lib }}"
+          wget -q "https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/${LIB}" -O "${LIB}" || true
+          if [ -f "${LIB}" ]; then
+            sha256sum "${LIB}" > "${LIB}.sha256"
+          fi
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: orly-${{ matrix.platform }}
+          path: |
+            orly-*
+            libsecp256k1*
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Get version
+        id: version
+        run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Create combined checksums
+        run: |
+          cd artifacts
+          cat *.sha256 | sort -k2 > SHA256SUMS.txt
+          rm -f *.sha256
+
+      - name: List release files
+        run: ls -la artifacts/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: ORLY ${{ steps.version.outputs.version }}
+          body: |
+            ## ORLY ${{ steps.version.outputs.version }}
+
+            ### Downloads
+
+            Download the appropriate binary for your platform. The `libsecp256k1` library is optional but recommended for better cryptographic performance.
+
+            ### Installation
+
+            1. Download the binary for your platform
+            2. (Optional) Download the corresponding `libsecp256k1` library
+            3. Place both files in the same directory
+            4. Make the binary executable: `chmod +x orly-*`
+            5. Run: `./orly-*-linux-amd64` (or your platform's binary)
+
+            ### Verify Downloads
+
+            ```bash
+            sha256sum -c SHA256SUMS.txt
+            ```
+
+            ### Configuration
+
+            See the [repository documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration options.
+          files: |
+            artifacts/*
+          draft: false
+          prerelease: false

.plan/issue-7-directory-spider.md

@@ -0,0 +1,442 @@
+# Implementation Plan: Directory Spider (Issue #7)
+
+## Overview
+
+Add a new "directory spider" that discovers relays by crawling kind 10002 (relay list) events, expanding outward in hops from whitelisted users, and then fetches essential metadata events (kinds 0, 3, 10000, 10002) from the discovered network.
+
+**Key Characteristics:**
+- Runs once per day (configurable)
+- Single-threaded, serial operations to minimize load
+- 3-hop relay discovery from whitelisted users
+- Fetches: kind 0 (profile), 3 (follow list), 10000 (mute list), 10002 (relay list)
+
+---
+
+## Architecture
+
+### New Package Structure
+
+```
+pkg/spider/
+├── spider.go           # Existing follows spider
+├── directory.go        # NEW: Directory spider implementation
+├── directory_test.go   # NEW: Tests
+└── common.go           # NEW: Shared utilities (extract from spider.go)
+```
+
+### Core Components
+
+```go
+// DirectorySpider manages the daily relay discovery and metadata sync
+type DirectorySpider struct {
+    ctx        context.Context
+    cancel     context.CancelFunc
+    db         *database.D
+    pub        publisher.I
+
+    // Configuration
+    interval   time.Duration  // Default: 24h
+    maxHops    int            // Default: 3
+
+    // State
+    running    atomic.Bool
+    lastRun    time.Time
+
+    // Relay discovery
+    discoveredRelays map[string]int  // URL -> hop distance
+    processedRelays  map[string]bool // Already fetched from
+
+    // Callbacks for integration
+    getSeedPubkeys func() [][]byte  // Whitelisted users (from ACL)
+}
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Directory Spider Structure
+
+**File:** `pkg/spider/directory.go`
+
+1. **Create DirectorySpider struct** with:
+   - Context management for cancellation
+   - Database and publisher references
+   - Configuration (interval, max hops)
+   - State tracking (discovered relays, processed relays)
+
+2. **Constructor:** `NewDirectorySpider(ctx, db, pub, interval, maxHops)`
+   - Initialize maps and state
+   - Set defaults (24h interval, 3 hops)
+
+3. **Lifecycle methods:**
+   - `Start()` - Launch main goroutine
+   - `Stop()` - Cancel context and wait for shutdown
+   - `TriggerNow()` - Force immediate run (for testing/admin)
+
+### Phase 2: Relay Discovery (3-Hop Expansion)
+
+**Algorithm:**
+
+```
+Round 1: Get relay lists from whitelisted users
+  - Query local DB for kind 10002 events from seed pubkeys
+  - Extract relay URLs from "r" tags
+  - Mark as hop 0 relays
+
+Round 2-4 (3 iterations):
+  - For each relay at current hop level (in serial):
+    1. Connect to relay
+    2. Query for ALL kind 10002 events (limit: 5000)
+    3. Extract new relay URLs
+    4. Mark as hop N+1 relays
+    5. Close connection
+    6. Sleep briefly between relays (rate limiting)
+```
+
+**Key Methods:**
+
+```go
+// discoverRelays performs the 3-hop relay expansion
+func (ds *DirectorySpider) discoverRelays(ctx context.Context) error
+
+// fetchRelayListsFromRelay connects to a relay and fetches kind 10002 events
+func (ds *DirectorySpider) fetchRelayListsFromRelay(ctx context.Context, relayURL string) ([]*event.T, error)
+
+// extractRelaysFromEvents parses kind 10002 events and extracts relay URLs
+func (ds *DirectorySpider) extractRelaysFromEvents(events []*event.T) []string
+```
+
+### Phase 3: Metadata Fetching
+
+After relay discovery, fetch essential metadata from all discovered relays:
+
+**Kinds to fetch:**
+- Kind 0: Profile metadata (replaceable)
+- Kind 3: Follow lists (replaceable)
+- Kind 10000: Mute lists (replaceable)
+- Kind 10002: Relay lists (already have many, but get latest)
+
+**Fetch Strategy:**
+
+```go
+// fetchMetadataFromRelays iterates through discovered relays serially
+func (ds *DirectorySpider) fetchMetadataFromRelays(ctx context.Context) error {
+    for relayURL := range ds.discoveredRelays {
+        // Skip if already processed
+        if ds.processedRelays[relayURL] {
+            continue
+        }
+
+        // Fetch each kind type
+        for _, k := range []int{0, 3, 10000, 10002} {
+            events, err := ds.fetchKindFromRelay(ctx, relayURL, k)
+            // Store events...
+        }
+
+        ds.processedRelays[relayURL] = true
+
+        // Rate limiting sleep
+        time.Sleep(500 * time.Millisecond)
+    }
+}
+```
+
+**Query Filters:**
+- For replaceable events (0, 3, 10000, 10002): No time filter, let relay return latest
+- Limit per query: 1000-5000 events
+- Use pagination if relay supports it
+
+### Phase 4: WebSocket Client for Fetching
+
+**Reuse existing patterns from spider.go:**
+
+```go
+// fetchFromRelay handles connection, query, and cleanup
+func (ds *DirectorySpider) fetchFromRelay(ctx context.Context, relayURL string, f *filter.F) ([]*event.T, error) {
+    // Create timeout context (30 seconds per relay)
+    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+    defer cancel()
+
+    // Connect using ws.Client (from pkg/protocol/ws)
+    client, err := ws.NewClient(ctx, relayURL)
+    if err != nil {
+        return nil, err
+    }
+    defer client.Close()
+
+    // Subscribe with filter
+    sub, err := client.Subscribe(ctx, f)
+    if err != nil {
+        return nil, err
+    }
+
+    // Collect events until EOSE or timeout
+    var events []*event.T
+    for ev := range sub.Events {
+        events = append(events, ev)
+    }
+
+    return events, nil
+}
+```
+
+### Phase 5: Event Storage
+
+**Storage Strategy:**
+
+```go
+func (ds *DirectorySpider) storeEvents(ctx context.Context, events []*event.T) (saved, duplicates int) {
+    for _, ev := range events {
+        _, err := ds.db.SaveEvent(ctx, ev)
+        if err != nil {
+            if errors.Is(err, database.ErrDuplicate) {
+                duplicates++
+                continue
+            }
+            // Log other errors but continue
+            log.W.F("failed to save event %s: %v", ev.ID.String(), err)
+            continue
+        }
+        saved++
+
+        // Publish to active subscribers
+        ds.pub.Deliver(ev)
+    }
+    return
+}
+```
+
+### Phase 6: Main Loop
+
+```go
+func (ds *DirectorySpider) mainLoop() {
+    // Calculate time until next run
+    ticker := time.NewTicker(ds.interval)
+    defer ticker.Stop()
+
+    // Run immediately on start
+    ds.runOnce()
+
+    for {
+        select {
+        case <-ds.ctx.Done():
+            return
+        case <-ticker.C:
+            ds.runOnce()
+        }
+    }
+}
+
+func (ds *DirectorySpider) runOnce() {
+    if !ds.running.CompareAndSwap(false, true) {
+        log.I.F("directory spider already running, skipping")
+        return
+    }
+    defer ds.running.Store(false)
+
+    log.I.F("starting directory spider run")
+    start := time.Now()
+
+    // Reset state
+    ds.discoveredRelays = make(map[string]int)
+    ds.processedRelays = make(map[string]bool)
+
+    // Phase 1: Discover relays via 3-hop expansion
+    if err := ds.discoverRelays(ds.ctx); err != nil {
+        log.E.F("relay discovery failed: %v", err)
+        return
+    }
+    log.I.F("discovered %d relays", len(ds.discoveredRelays))
+
+    // Phase 2: Fetch metadata from all relays
+    if err := ds.fetchMetadataFromRelays(ds.ctx); err != nil {
+        log.E.F("metadata fetch failed: %v", err)
+        return
+    }
+
+    ds.lastRun = time.Now()
+    log.I.F("directory spider completed in %v", time.Since(start))
+}
+```
+
+### Phase 7: Configuration
+
+**New environment variables:**
+
+```go
+// In app/config/config.go
+DirectorySpiderEnabled  bool          `env:"ORLY_DIRECTORY_SPIDER" default:"false" usage:"enable directory spider for metadata sync"`
+DirectorySpiderInterval time.Duration `env:"ORLY_DIRECTORY_SPIDER_INTERVAL" default:"24h" usage:"how often to run directory spider"`
+DirectorySpiderMaxHops  int           `env:"ORLY_DIRECTORY_SPIDER_HOPS" default:"3" usage:"maximum hops for relay discovery"`
+```
+
+### Phase 8: Integration with app/main.go
+
+```go
+// After existing spider initialization
+if badgerDB, ok := db.(*database.D); ok && cfg.DirectorySpiderEnabled {
+    l.directorySpider, err = spider.NewDirectorySpider(
+        ctx,
+        badgerDB,
+        l.publishers,
+        cfg.DirectorySpiderInterval,
+        cfg.DirectorySpiderMaxHops,
+    )
+    if err != nil {
+        return nil, fmt.Errorf("failed to create directory spider: %w", err)
+    }
+
+    // Set callback to get seed pubkeys from ACL
+    l.directorySpider.SetSeedCallback(func() [][]byte {
+        // Get whitelisted users from all ACLs
+        var pubkeys [][]byte
+        for _, aclInstance := range acl.Registry.ACL {
+            if follows, ok := aclInstance.(*acl.Follows); ok {
+                pubkeys = append(pubkeys, follows.GetFollowedPubkeys()...)
+            }
+        }
+        return pubkeys
+    })
+
+    l.directorySpider.Start()
+}
+```
+
+---
+
+## Self-Relay Detection
+
+Reuse the existing `isSelfRelay()` pattern from spider.go:
+
+```go
+func (ds *DirectorySpider) isSelfRelay(relayURL string) bool {
+    // Use NIP-11 to get relay pubkey
+    // Compare against our relay identity pubkey
+    // Cache results to avoid repeated requests
+}
+```
+
+---
+
+## Error Handling & Resilience
+
+1. **Connection Timeouts:** 30 seconds per relay
+2. **Query Timeouts:** 60 seconds per query
+3. **Graceful Degradation:** Continue to next relay on failure
+4. **Rate Limiting:** 500ms sleep between relays
+5. **Memory Limits:** Process events in batches of 1000
+6. **Context Cancellation:** Check at each step for shutdown
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+```go
+// pkg/spider/directory_test.go
+
+func TestExtractRelaysFromEvents(t *testing.T)
+func TestDiscoveryHopTracking(t *testing.T)
+func TestSelfRelayFiltering(t *testing.T)
+```
+
+### Integration Tests
+
+```go
+func TestDirectorySpiderE2E(t *testing.T) {
+    // Start test relay
+    // Populate with kind 10002 events
+    // Run directory spider
+    // Verify events fetched and stored
+}
+```
+
+---
+
+## Logging
+
+Use existing `lol.mleku.dev` logging patterns:
+
+```go
+log.I.F("directory spider: starting relay discovery")
+log.D.F("directory spider: hop %d, discovered %d new relays", hop, count)
+log.W.F("directory spider: failed to connect to %s: %v", url, err)
+log.E.F("directory spider: critical error: %v", err)
+```
+
+---
+
+## Implementation Order
+
+1. **Phase 1:** Core struct and lifecycle (1-2 hours)
+2. **Phase 2:** Relay discovery with hop expansion (2-3 hours)
+3. **Phase 3:** Metadata fetching (1-2 hours)
+4. **Phase 4:** WebSocket client integration (1 hour)
+5. **Phase 5:** Event storage (30 min)
+6. **Phase 6:** Main loop and scheduling (1 hour)
+7. **Phase 7:** Configuration (30 min)
+8. **Phase 8:** Integration with main.go (30 min)
+9. **Testing:** Unit and integration tests (2-3 hours)
+
+**Total Estimate:** 10-14 hours
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- Web UI status page for directory spider
+- Metrics/stats collection (relays discovered, events fetched)
+- Configurable kind list to fetch
+- Priority ordering of relays (closer hops first)
+- Persistent relay discovery cache between runs
+
+---
+
+## Dependencies
+
+**Existing packages to use:**
+- `pkg/protocol/ws` - WebSocket client
+- `pkg/database` - Event storage
+- `pkg/encoders/filter` - Query filter construction
+- `pkg/acl` - Get whitelisted users
+- `pkg/sync` - NIP-11 cache for self-detection (if needed)
+
+**No new external dependencies required.**
+
+---
+
+## Follow-up Items (Post-Implementation)
+
+### TODO: Verify Connection Behavior is Not Overly Aggressive
+
+**Issue:** The current implementation creates a **new WebSocket connection for each kind query** when fetching metadata. For each relay, this means:
+1. Connect → fetch kind 0 → disconnect
+2. Connect → fetch kind 3 → disconnect
+3. Connect → fetch kind 10000 → disconnect
+4. Connect → fetch kind 10002 → disconnect
+
+This could be seen as aggressive by remote relays and may trigger rate limiting or IP bans.
+
+**Verification needed:**
+- [ ] Monitor logs with `ORLY_LOG_LEVEL=debug` to see per-kind fetch results
+- [ ] Check if relays are returning events for all 4 kinds or just kind 0
+- [ ] Look for WARNING logs about connection failures or rate limiting
+- [ ] Verify the 500ms delay between relays is sufficient
+
+**Potential optimization (if needed):**
+- Refactor `fetchMetadataFromRelays()` to use a single connection per relay
+- Fetch all 4 kinds using multiple subscriptions on one connection
+- Example pattern:
+  ```go
+  client, err := ws.RelayConnect(ctx, relayURL)
+  defer client.Close()
+
+  for _, k := range kindsToFetch {
+      events, _ := fetchKindOnConnection(client, k)
+      // ...
+  }
+  ```
+
+**Priority:** Medium - only optimize if monitoring shows issues with the current approach

.plan/policy-hot-reload-implementation.md

@@ -0,0 +1,974 @@
+# Implementation Plan: Policy Hot Reload, Follow List Whitelisting, and Web UI
+
+**Issue:** https://git.nostrdev.com/mleku/next.orly.dev/issues/6
+
+## Overview
+
+This plan implements three interconnected features for ORLY's policy system:
+1. **Dynamic Policy Configuration** via kind 12345 events (hot reload)
+2. **Administrator Follow List Whitelisting** within the policy system
+3. **Web Interface** for policy management with JSON editing
+
+## Architecture Summary
+
+### Current System Analysis
+
+**Policy System** ([pkg/policy/policy.go](pkg/policy/policy.go)):
+- Policy loaded from `~/.config/ORLY/policy.json` at startup
+- `P` struct with unexported `rules` field (map[int]Rule)
+- `PolicyManager` manages script runners for external policy scripts
+- `LoadFromFile()` method exists for loading policy from disk
+- No hot reload mechanism currently exists
+
+**ACL System** ([pkg/acl/follows.go](pkg/acl/follows.go)):
+- Separate from policy system
+- Manages admin/owner/follows lists for write access control
+- Fetches kind 3 events from relays
+- Has callback mechanism for updates
+
+**Event Handling** ([app/handle-event.go](app/handle-event.go)):213-226
+- Special handling for NIP-43 events (join/leave requests)
+- Pattern: Check kind early, process, return early
+
+**Web UI**:
+- Svelte-based component architecture
+- Tab-based navigation in [app/web/src/App.svelte](app/web/src/App.svelte)
+- API endpoints follow `/api/<feature>/<action>` pattern
+
+## Feature 1: Dynamic Policy Configuration (Kind 12345)
+
+### Design
+
+**Event Kind:** 12345 (Relay Policy Configuration)
+**Purpose:** Allow admins/owners to update policy configuration via Nostr event
+**Security:** Only admins/owners can publish; only visible to admins/owners
+**Process Flow:**
+1. Admin/owner creates kind 12345 event with JSON policy in `content` field
+2. Relay receives event via WebSocket
+3. Validate sender is admin/owner
+4. Pause policy manager (stop script runners)
+5. Parse and validate JSON configuration
+6. Apply new policy configuration
+7. Persist to `~/.config/ORLY/policy.json`
+8. Resume policy manager (restart script runners)
+9. Send OK response
+
+### Implementation Steps
+
+#### Step 1.1: Define Kind Constant
+**File:** Create `pkg/protocol/policyconfig/policyconfig.go`
+```go
+package policyconfig
+
+const (
+    // KindPolicyConfig is a relay-internal event for policy configuration updates
+    // Only visible to admins and owners
+    KindPolicyConfig uint16 = 12345
+)
+```
+
+#### Step 1.2: Add Policy Hot Reload Methods
+**File:** [pkg/policy/policy.go](pkg/policy/policy.go)
+
+Add methods to `P` struct:
+```go
+// Reload loads policy from JSON bytes and applies it to the existing policy instance
+// This pauses the policy manager, updates configuration, and resumes
+func (p *P) Reload(policyJSON []byte) error
+
+// Pause pauses the policy manager and stops all script runners
+func (p *P) Pause() error
+
+// Resume resumes the policy manager and restarts script runners
+func (p *P) Resume() error
+
+// SaveToFile persists the current policy configuration to disk
+func (p *P) SaveToFile(configPath string) error
+```
+
+**Implementation Details:**
+- `Reload()` should:
+  - Call `Pause()` to stop all script runners
+  - Unmarshal JSON into policy struct (using shadow struct pattern)
+  - Validate configuration
+  - Populate binary caches
+  - Call `SaveToFile()` to persist
+  - Call `Resume()` to restart scripts
+  - Return error if any step fails
+
+- `Pause()` should:
+  - Iterate through `p.manager.runners` map
+  - Call `Stop()` on each runner
+  - Set a paused flag on the manager
+
+- `Resume()` should:
+  - Clear paused flag
+  - Call `startPolicyIfExists()` to restart default script
+  - Restart any rule-specific scripts that were running
+
+- `SaveToFile()` should:
+  - Marshal policy to JSON (using pJSON shadow struct)
+  - Write atomically to config path (write to temp file, then rename)
+
+#### Step 1.3: Handle Kind 12345 Events
+**File:** [app/handle-event.go](app/handle-event.go)
+
+Add handling after NIP-43 special events (after line 226):
+```go
+// Handle policy configuration update events (kind 12345)
+case policyconfig.KindPolicyConfig:
+    // Process policy config update and return early
+    if err = l.HandlePolicyConfigUpdate(env.E); chk.E(err) {
+        log.E.F("failed to process policy config update: %v", err)
+        if err = Ok.Error(l, env, err.Error()); chk.E(err) {
+            return
+        }
+        return
+    }
+    // Send OK response
+    if err = Ok.Ok(l, env, "policy configuration updated"); chk.E(err) {
+        return
+    }
+    return
+```
+
+Create new file: `app/handle-policy-config.go`
+```go
+// HandlePolicyConfigUpdate processes kind 12345 policy configuration events
+// Only admins and owners can update policy configuration
+func (l *Listener) HandlePolicyConfigUpdate(ev *event.E) error {
+    // 1. Verify sender is admin or owner
+    // 2. Parse JSON from event content
+    // 3. Validate JSON structure
+    // 4. Call l.policyManager.Reload(jsonBytes)
+    // 5. Log success/failure
+    return nil
+}
+```
+
+**Security Checks:**
+- Verify `ev.Pubkey` is in admins or owners list
+- Validate JSON syntax before applying
+- Catch all errors and return descriptive messages
+- Log all policy update attempts (success and failure)
+
+#### Step 1.4: Query Filtering (Optional)
+**File:** [app/handle-req.go](app/handle-req.go)
+
+Add filter to hide kind 12345 from non-admins:
+```go
+// In handleREQ, after ACL checks:
+// Filter out policy config events (kind 12345) for non-admin users
+if !isAdminOrOwner(l.authedPubkey.Load(), l.Admins, l.Owners) {
+    // Remove kind 12345 from filter
+    for _, f := range filters {
+        f.Kinds.Remove(policyconfig.KindPolicyConfig)
+    }
+}
+```
+
+## Feature 2: Administrator Follow List Whitelisting
+
+### Design
+
+**Purpose:** Enable policy-based follow list whitelisting (separate from ACL follows)
+**Use Case:** Policy admins can designate follows who get special policy privileges
+**Configuration:**
+```json
+{
+  "policy_admins": ["admin_pubkey_hex_1", "admin_pubkey_hex_2"],
+  "policy_follow_whitelist_enabled": true,
+  "rules": {
+    "1": {
+      "write_allow_follows": true  // Allow writes from policy admin follows
+    }
+  }
+}
+```
+
+### Implementation Steps
+
+#### Step 2.1: Extend Policy Configuration Structure
+**File:** [pkg/policy/policy.go](pkg/policy/policy.go)
+
+Extend `P` struct:
+```go
+type P struct {
+    Kind          Kinds  `json:"kind"`
+    rules         map[int]Rule
+    Global        Rule   `json:"global"`
+    DefaultPolicy string `json:"default_policy"`
+
+    // New fields for follow list whitelisting
+    PolicyAdmins                   []string `json:"policy_admins,omitempty"`
+    PolicyFollowWhitelistEnabled   bool     `json:"policy_follow_whitelist_enabled,omitempty"`
+
+    // Unexported cached data
+    policyAdminsBin  [][]byte     // Binary cache for admin pubkeys
+    policyFollows    [][]byte     // Cached follow list from policy admins
+    policyFollowsMx  sync.RWMutex // Protect follows list
+
+    manager *PolicyManager
+}
+```
+
+Extend `Rule` struct:
+```go
+type Rule struct {
+    // ... existing fields ...
+
+    // New field for follow-based whitelisting
+    WriteAllowFollows bool `json:"write_allow_follows,omitempty"`
+    ReadAllowFollows  bool `json:"read_allow_follows,omitempty"`
+}
+```
+
+Update `pJSON` shadow struct to include new fields.
+
+#### Step 2.2: Add Follow List Fetching
+**File:** [pkg/policy/policy.go](pkg/policy/policy.go)
+
+Add methods:
+```go
+// FetchPolicyFollows fetches follow lists (kind 3) from database for policy admins
+// This is called during policy load and can be called periodically
+func (p *P) FetchPolicyFollows(db database.D) error {
+    p.policyFollowsMx.Lock()
+    defer p.policyFollowsMx.Unlock()
+
+    // Clear existing follows
+    p.policyFollows = nil
+
+    // For each policy admin, query kind 3 events
+    for _, adminPubkey := range p.policyAdminsBin {
+        // Build filter for kind 3 from this admin
+        // Query database for latest kind 3 event
+        // Extract p-tags from event
+        // Add to p.policyFollows list
+    }
+
+    return nil
+}
+
+// IsPolicyFollow checks if pubkey is in policy admin follows
+func (p *P) IsPolicyFollow(pubkey []byte) bool {
+    p.policyFollowsMx.RLock()
+    defer p.policyFollowsMx.RUnlock()
+
+    for _, follow := range p.policyFollows {
+        if utils.FastEqual(pubkey, follow) {
+            return true
+        }
+    }
+    return false
+}
+```
+
+#### Step 2.3: Integrate Follow Checking in Policy Rules
+**File:** [pkg/policy/policy.go](pkg/policy/policy.go)
+
+Update `checkRulePolicy()` method (around line 1062):
+```go
+// In write access checks, after checking write_allow list:
+if access == "write" {
+    // Check if follow-based whitelisting is enabled for this rule
+    if rule.WriteAllowFollows && p.PolicyFollowWhitelistEnabled {
+        if p.IsPolicyFollow(loggedInPubkey) {
+            return true, nil  // Allow write from policy admin follow
+        }
+    }
+
+    // Continue with existing write_allow checks...
+}
+
+// Similar for read access:
+if access == "read" {
+    if rule.ReadAllowFollows && p.PolicyFollowWhitelistEnabled {
+        if p.IsPolicyFollow(loggedInPubkey) {
+            return true, nil  // Allow read from policy admin follow
+        }
+    }
+    // Continue with existing read_allow checks...
+}
+```
+
+#### Step 2.4: Periodic Follow List Refresh
+**File:** [pkg/policy/policy.go](pkg/policy/policy.go)
+
+Add to `NewWithManager()`:
+```go
+// Start periodic follow list refresh for policy admins
+if len(policy.PolicyAdmins) > 0 && policy.PolicyFollowWhitelistEnabled {
+    go policy.startPeriodicFollowRefresh(ctx)
+}
+```
+
+Add method:
+```go
+// startPeriodicFollowRefresh periodically fetches policy admin follow lists
+func (p *P) startPeriodicFollowRefresh(ctx context.Context) {
+    ticker := time.NewTicker(15 * time.Minute) // Refresh every 15 minutes
+    defer ticker.Stop()
+
+    // Fetch immediately on startup
+    if err := p.FetchPolicyFollows(p.db); err != nil {
+        log.E.F("failed to fetch policy follows: %v", err)
+    }
+
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        case <-ticker.C:
+            if err := p.FetchPolicyFollows(p.db); err != nil {
+                log.E.F("failed to fetch policy follows: %v", err)
+            } else {
+                log.I.F("refreshed policy admin follow lists")
+            }
+        }
+    }
+}
+```
+
+**Note:** Need to pass database reference to policy manager. Update `NewWithManager()` signature:
+```go
+func NewWithManager(ctx context.Context, appName string, enabled bool, db *database.D) *P
+```
+
+## Feature 3: Web Interface for Policy Management
+
+### Design
+
+**Components:**
+1. `PolicyView.svelte` - Main policy management UI
+2. API endpoints for policy CRUD operations
+3. JSON editor with validation
+4. Follow list viewer
+
+**UI Features:**
+- View current policy configuration (read-only JSON display)
+- Edit policy JSON with syntax highlighting
+- Validate JSON before publishing
+- Publish kind 12345 event to update policy
+- View policy admin pubkeys
+- View follow lists for each policy admin
+- Add/remove policy admin pubkeys (updates and republishes config)
+
+### Implementation Steps
+
+#### Step 3.1: Create Policy View Component
+**File:** `app/web/src/PolicyView.svelte`
+
+Structure:
+```svelte
+<script>
+    export let isLoggedIn = false;
+    export let userRole = "";
+    export let policyConfig = null;
+    export let policyAdmins = [];
+    export let policyFollows = [];
+    export let isLoadingPolicy = false;
+    export let policyMessage = "";
+    export let policyMessageType = "info";
+    export let policyEditJson = "";
+
+    import { createEventDispatcher } from "svelte";
+    const dispatch = createEventDispatcher();
+
+    // Event handlers
+    function loadPolicy() { dispatch("loadPolicy"); }
+    function savePolicy() { dispatch("savePolicy"); }
+    function validatePolicy() { dispatch("validatePolicy"); }
+    function addPolicyAdmin() { dispatch("addPolicyAdmin"); }
+    function removePolicyAdmin(pubkey) { dispatch("removePolicyAdmin", pubkey); }
+    function refreshFollows() { dispatch("refreshFollows"); }
+</script>
+
+<div class="policy-view">
+    <h2>Policy Configuration Management</h2>
+
+    {#if isLoggedIn && (userRole === "owner" || userRole === "admin")}
+        <!-- Policy JSON Editor Section -->
+        <div class="policy-section">
+            <h3>Policy Configuration</h3>
+            <div class="policy-controls">
+                <button on:click={loadPolicy}>🔄 Reload</button>
+                <button on:click={validatePolicy}>✓ Validate</button>
+                <button on:click={savePolicy}>📤 Publish Update</button>
+            </div>
+
+            <textarea
+                class="policy-editor"
+                bind:value={policyEditJson}
+                spellcheck="false"
+                placeholder="Policy JSON configuration..."
+            />
+        </div>
+
+        <!-- Policy Admins Section -->
+        <div class="policy-admins-section">
+            <h3>Policy Administrators</h3>
+            <p class="section-description">
+                Policy admins can update configuration and their follows get whitelisted
+                (if policy_follow_whitelist_enabled is true)
+            </p>
+
+            <div class="admin-list">
+                {#each policyAdmins as admin}
+                    <div class="admin-item">
+                        <span class="admin-pubkey">{admin}</span>
+                        <button
+                            class="remove-btn"
+                            on:click={() => removePolicyAdmin(admin)}
+                        >
+                            Remove
+                        </button>
+                    </div>
+                {/each}
+            </div>
+
+            <div class="add-admin">
+                <input
+                    type="text"
+                    placeholder="npub or hex pubkey"
+                    id="new-admin-input"
+                />
+                <button on:click={addPolicyAdmin}>Add Admin</button>
+            </div>
+        </div>
+
+        <!-- Follow List Section -->
+        <div class="policy-follows-section">
+            <h3>Policy Follow Whitelist</h3>
+            <button on:click={refreshFollows}>🔄 Refresh Follows</button>
+
+            <div class="follows-list">
+                {#if policyFollows.length === 0}
+                    <p class="no-follows">No follows loaded</p>
+                {:else}
+                    <p class="follows-count">
+                        {policyFollows.length} pubkey(s) in whitelist
+                    </p>
+                    <div class="follows-grid">
+                        {#each policyFollows as follow}
+                            <div class="follow-item">{follow}</div>
+                        {/each}
+                    </div>
+                {/if}
+            </div>
+        </div>
+
+        <!-- Message Display -->
+        {#if policyMessage}
+            <div class="policy-message {policyMessageType}">
+                {policyMessage}
+            </div>
+        {/if}
+    {:else}
+        <div class="access-denied">
+            <p>Policy management is only available to relay administrators and owners.</p>
+            {#if !isLoggedIn}
+                <button on:click={() => dispatch("openLoginModal")}>
+                    Login
+                </button>
+            {/if}
+        </div>
+    {/if}
+</div>
+
+<style>
+    /* Policy-specific styling */
+    .policy-view { /* ... */ }
+    .policy-editor {
+        width: 100%;
+        min-height: 400px;
+        font-family: 'Monaco', 'Courier New', monospace;
+        font-size: 0.9em;
+        padding: 1em;
+        border: 1px solid var(--border-color);
+        border-radius: 4px;
+        background: var(--code-bg);
+        color: var(--code-text);
+    }
+    /* ... more styles ... */
+</style>
+```
+
+#### Step 3.2: Add Policy Tab to Main App
+**File:** [app/web/src/App.svelte](app/web/src/App.svelte)
+
+Add state variables (around line 94):
+```javascript
+// Policy management state
+let policyConfig = null;
+let policyAdmins = [];
+let policyFollows = [];
+let isLoadingPolicy = false;
+let policyMessage = "";
+let policyMessageType = "info";
+let policyEditJson = "";
+```
+
+Add tab definition in `tabs` array (look for export/import/sprocket tabs):
+```javascript
+if (isLoggedIn && (userRole === "owner" || userRole === "admin")) {
+    tabs.push({
+        id: "policy",
+        label: "Policy",
+        icon: "🛡️",
+        isSearchTab: false
+    });
+}
+```
+
+Add component import:
+```javascript
+import PolicyView from "./PolicyView.svelte";
+```
+
+Add view in main content area (look for {#if selectedTab === "sprocket"}):
+```svelte
+{:else if selectedTab === "policy"}
+    <PolicyView
+        {isLoggedIn}
+        {userRole}
+        {policyConfig}
+        {policyAdmins}
+        {policyFollows}
+        {isLoadingPolicy}
+        {policyMessage}
+        {policyMessageType}
+        bind:policyEditJson
+        on:loadPolicy={handleLoadPolicy}
+        on:savePolicy={handleSavePolicy}
+        on:validatePolicy={handleValidatePolicy}
+        on:addPolicyAdmin={handleAddPolicyAdmin}
+        on:removePolicyAdmin={handleRemovePolicyAdmin}
+        on:refreshFollows={handleRefreshFollows}
+        on:openLoginModal={() => (showLoginModal = true)}
+    />
+```
+
+Add event handlers:
+```javascript
+async function handleLoadPolicy() {
+    isLoadingPolicy = true;
+    policyMessage = "";
+
+    try {
+        const response = await fetch("/api/policy/config", {
+            credentials: "include"
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to load policy: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        policyConfig = data.config;
+        policyEditJson = JSON.stringify(data.config, null, 2);
+        policyAdmins = data.config.policy_admins || [];
+
+        policyMessage = "Policy loaded successfully";
+        policyMessageType = "success";
+    } catch (error) {
+        policyMessage = `Error loading policy: ${error.message}`;
+        policyMessageType = "error";
+        console.error("Error loading policy:", error);
+    } finally {
+        isLoadingPolicy = false;
+    }
+}
+
+async function handleSavePolicy() {
+    isLoadingPolicy = true;
+    policyMessage = "";
+
+    try {
+        // Validate JSON first
+        const config = JSON.parse(policyEditJson);
+
+        // Publish kind 12345 event via websocket with auth
+        const event = {
+            kind: 12345,
+            content: policyEditJson,
+            tags: [],
+            created_at: Math.floor(Date.now() / 1000)
+        };
+
+        const result = await publishEventWithAuth(event, userSigner);
+
+        if (result.success) {
+            policyMessage = "Policy updated successfully";
+            policyMessageType = "success";
+            // Reload to get updated config
+            await handleLoadPolicy();
+        } else {
+            throw new Error(result.message || "Failed to publish policy update");
+        }
+    } catch (error) {
+        policyMessage = `Error updating policy: ${error.message}`;
+        policyMessageType = "error";
+        console.error("Error updating policy:", error);
+    } finally {
+        isLoadingPolicy = false;
+    }
+}
+
+function handleValidatePolicy() {
+    try {
+        JSON.parse(policyEditJson);
+        policyMessage = "Policy JSON is valid ✓";
+        policyMessageType = "success";
+    } catch (error) {
+        policyMessage = `Invalid JSON: ${error.message}`;
+        policyMessageType = "error";
+    }
+}
+
+async function handleRefreshFollows() {
+    isLoadingPolicy = true;
+    policyMessage = "";
+
+    try {
+        const response = await fetch("/api/policy/follows", {
+            credentials: "include"
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to load follows: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        policyFollows = data.follows || [];
+
+        policyMessage = `Loaded ${policyFollows.length} follows`;
+        policyMessageType = "success";
+    } catch (error) {
+        policyMessage = `Error loading follows: ${error.message}`;
+        policyMessageType = "error";
+        console.error("Error loading follows:", error);
+    } finally {
+        isLoadingPolicy = false;
+    }
+}
+
+async function handleAddPolicyAdmin(event) {
+    // Get input value
+    const input = document.getElementById("new-admin-input");
+    const pubkey = input.value.trim();
+
+    if (!pubkey) {
+        policyMessage = "Please enter a pubkey";
+        policyMessageType = "error";
+        return;
+    }
+
+    try {
+        // Convert npub to hex if needed (implement or use nostr library)
+        // Add to policy_admins array in config
+        const config = JSON.parse(policyEditJson);
+        if (!config.policy_admins) {
+            config.policy_admins = [];
+        }
+        if (!config.policy_admins.includes(pubkey)) {
+            config.policy_admins.push(pubkey);
+            policyEditJson = JSON.stringify(config, null, 2);
+            input.value = "";
+            policyMessage = "Admin added (click Publish to save)";
+            policyMessageType = "info";
+        } else {
+            policyMessage = "Admin already in list";
+            policyMessageType = "warning";
+        }
+    } catch (error) {
+        policyMessage = `Error adding admin: ${error.message}`;
+        policyMessageType = "error";
+    }
+}
+
+async function handleRemovePolicyAdmin(event) {
+    const pubkey = event.detail;
+
+    try {
+        const config = JSON.parse(policyEditJson);
+        if (config.policy_admins) {
+            config.policy_admins = config.policy_admins.filter(p => p !== pubkey);
+            policyEditJson = JSON.stringify(config, null, 2);
+            policyMessage = "Admin removed (click Publish to save)";
+            policyMessageType = "info";
+        }
+    } catch (error) {
+        policyMessage = `Error removing admin: ${error.message}`;
+        policyMessageType = "error";
+    }
+}
+```
+
+#### Step 3.3: Add API Endpoints
+**File:** [app/server.go](app/server.go)
+
+Add to route registration (around line 245):
+```go
+// Policy management endpoints (admin/owner only)
+s.mux.HandleFunc("/api/policy/config", s.handlePolicyConfig)
+s.mux.HandleFunc("/api/policy/follows", s.handlePolicyFollows)
+```
+
+Create new file: `app/handle-policy-api.go`
+```go
+package app
+
+import (
+    "encoding/json"
+    "net/http"
+    "lol.mleku.dev/log"
+    "git.mleku.dev/mleku/nostr/encoders/hex"
+)
+
+// handlePolicyConfig returns the current policy configuration
+// GET /api/policy/config
+func (s *Server) handlePolicyConfig(w http.ResponseWriter, r *http.Request) {
+    // Verify authentication
+    session, err := s.getSession(r)
+    if err != nil || session == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+
+    // Verify user is admin or owner
+    role := s.getUserRole(session.Pubkey)
+    if role != "admin" && role != "owner" {
+        http.Error(w, "Forbidden", http.StatusForbidden)
+        return
+    }
+
+    // Get current policy configuration from policy manager
+    // This requires adding a method to get the raw config
+    config := s.policyManager.GetConfig() // Need to implement this
+
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(map[string]interface{}{
+        "config": config,
+    })
+}
+
+// handlePolicyFollows returns the policy admin follow lists
+// GET /api/policy/follows
+func (s *Server) handlePolicyFollows(w http.ResponseWriter, r *http.Request) {
+    // Verify authentication
+    session, err := s.getSession(r)
+    if err != nil || session == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+
+    // Verify user is admin or owner
+    role := s.getUserRole(session.Pubkey)
+    if role != "admin" && role != "owner" {
+        http.Error(w, "Forbidden", http.StatusForbidden)
+        return
+    }
+
+    // Get policy follows from policy manager
+    follows := s.policyManager.GetPolicyFollows() // Need to implement this
+
+    // Convert to hex strings for JSON response
+    followsHex := make([]string, len(follows))
+    for i, f := range follows {
+        followsHex[i] = hex.Enc(f)
+    }
+
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(map[string]interface{}{
+        "follows": followsHex,
+    })
+}
+```
+
+**Note:** Need to add getter methods to policy manager:
+```go
+// GetConfig returns the current policy configuration as a map
+// File: pkg/policy/policy.go
+func (p *P) GetConfig() map[string]interface{} {
+    // Marshal to JSON and back to get map representation
+    jsonBytes, _ := json.Marshal(p)
+    var config map[string]interface{}
+    json.Unmarshal(jsonBytes, &config)
+    return config
+}
+
+// GetPolicyFollows returns the current policy follow list
+func (p *P) GetPolicyFollows() [][]byte {
+    p.policyFollowsMx.RLock()
+    defer p.policyFollowsMx.RUnlock()
+
+    follows := make([][]byte, len(p.policyFollows))
+    copy(follows, p.policyFollows)
+    return follows
+}
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+1. **Policy Reload Tests** (`pkg/policy/policy_test.go`):
+   - Test `Reload()` with valid JSON
+   - Test `Reload()` with invalid JSON
+   - Test `Pause()` and `Resume()` functionality
+   - Test `SaveToFile()` atomic write
+
+2. **Follow List Tests** (`pkg/policy/follows_test.go`):
+   - Test `FetchPolicyFollows()` with mock database
+   - Test `IsPolicyFollow()` with various inputs
+   - Test follow list caching and expiry
+
+3. **Handler Tests** (`app/handle-policy-config_test.go`):
+   - Test kind 12345 handling with admin pubkey
+   - Test kind 12345 rejection from non-admin
+   - Test JSON validation errors
+
+### Integration Tests
+
+1. **End-to-End Policy Update**:
+   - Publish kind 12345 event as admin
+   - Verify policy reloaded
+   - Verify new policy enforced
+   - Verify policy persisted to disk
+
+2. **Follow Whitelist E2E**:
+   - Configure policy with follow whitelist enabled
+   - Add admin pubkey to policy_admins
+   - Publish kind 3 follow list for admin
+   - Verify follows can write/read per policy rules
+
+3. **Web UI E2E**:
+   - Load policy via API
+   - Edit and publish via UI
+   - Verify changes applied
+   - Check follow list display
+
+## Security Considerations
+
+1. **Authorization**:
+   - Only admins/owners can publish kind 12345
+   - Only admins/owners can access policy API endpoints
+   - Policy events only visible to admins/owners in queries
+
+2. **Validation**:
+   - Strict JSON schema validation before applying
+   - Rollback mechanism if policy fails to load
+   - Catch all parsing errors
+
+3. **Audit Trail**:
+   - Log all policy update attempts
+   - Store kind 12345 events in database for audit
+   - Include who changed what and when
+
+4. **Atomic Operations**:
+   - Pause-update-resume must be atomic
+   - File writes must be atomic (temp file + rename)
+   - No partial updates on failure
+
+## Migration Path
+
+### Phase 1: Backend Foundation
+1. Implement kind 12345 constant
+2. Add policy reload methods
+3. Add follow list support to policy
+4. Test hot reload mechanism
+
+### Phase 2: Event Handling
+1. Add kind 12345 handler
+2. Add API endpoints
+3. Test event flow end-to-end
+
+### Phase 3: Web UI
+1. Create PolicyView component
+2. Integrate into App.svelte
+3. Add JSON editor
+4. Test user workflows
+
+### Phase 4: Testing & Documentation
+1. Write comprehensive tests
+2. Update CLAUDE.md
+3. Create user documentation
+4. Add examples to docs/
+
+## Open Questions / Decisions Needed
+
+1. **Policy Admin vs Relay Admin**:
+   - Should policy_admins be separate from ORLY_ADMINS?
+   - **Recommendation:** Yes, separate. Policy admins manage policy, relay admins manage relay.
+
+2. **Follow List Refresh Frequency**:
+   - How often to refresh policy admin follows?
+   - **Recommendation:** 15 minutes (configurable via ORLY_POLICY_FOLLOW_REFRESH)
+
+3. **Backward Compatibility**:
+   - What happens to relays without policy_admins field?
+   - **Recommendation:** Fall back to empty list, disabled by default
+
+4. **Database Reference in Policy**:
+   - Policy needs database reference for follow queries
+   - **Recommendation:** Pass database to NewWithManager()
+
+5. **Error Handling on Reload Failure**:
+   - Should failed reload keep old policy or disable policy?
+   - **Recommendation:** Keep old policy, log error, return error to client
+
+## Success Criteria
+
+1. ✅ Admin can publish kind 12345 event with new policy JSON
+2. ✅ Relay receives event, validates sender, reloads policy without restart
+3. ✅ Policy persisted to `~/.config/ORLY/policy.json`
+4. ✅ Script runners paused during reload, resumed after
+5. ✅ Policy admins can be configured in policy JSON
+6. ✅ Policy admin follow lists fetched from database
+7. ✅ Follow-based whitelisting enforced in policy rules
+8. ✅ Web UI displays current policy configuration
+9. ✅ Web UI allows editing and validation of policy JSON
+10. ✅ Web UI shows policy admin follows
+11. ✅ Only admins/owners can access policy management
+12. ✅ All tests pass
+13. ✅ Documentation updated
+
+## Estimated Effort
+
+- **Backend (Policy + Event Handling):** 8-12 hours
+  - Policy reload methods: 3-4 hours
+  - Follow list support: 3-4 hours
+  - Event handling: 2-3 hours
+  - Testing: 2-3 hours
+
+- **API Endpoints:** 2-3 hours
+  - Route setup: 1 hour
+  - Handler implementation: 1-2 hours
+  - Testing: 1 hour
+
+- **Web UI:** 6-8 hours
+  - PolicyView component: 3-4 hours
+  - App integration: 2-3 hours
+  - Styling and UX: 2-3 hours
+  - Testing: 2 hours
+
+- **Documentation & Testing:** 4-6 hours
+  - Unit tests: 2-3 hours
+  - Integration tests: 2-3 hours
+  - Documentation: 2 hours
+
+**Total:** 20-29 hours
+
+## Dependencies
+
+- No external dependencies required
+- Uses existing ORLY infrastructure
+- Compatible with current policy system
+
+## Next Steps
+
+1. Review and approve this plan
+2. Clarify open questions/decisions
+3. Begin implementation in phases
+4. Iterative testing and refinement

ALL_FIXES.md

@@ -1,353 +0,0 @@
-# Complete WebSocket Stability Fixes - All Issues Resolved
-
-## Issues Identified & Fixed
-
-### 1. ⚠️ Publisher Not Delivering Events (CRITICAL)
-**Problem:** Events published but never delivered to subscribers
-
-**Root Cause:** Missing receiver channel in publisher
-- Subscription struct missing `Receiver` field
-- Publisher tried to send directly to write channel
-- Consumer goroutines never received events
-- Bypassed the khatru architecture
-
-**Solution:** Store and use receiver channels
-- Added `Receiver event.C` field to Subscription struct
-- Store receiver when registering subscriptions
-- Send events to receiver channel (not write channel)
-- Let consumer goroutines handle formatting and delivery
-
-**Files Modified:**
-- `app/publisher.go:32` - Added Receiver field to Subscription struct
-- `app/publisher.go:125,130` - Store receiver when registering
-- `app/publisher.go:242-266` - Send to receiver channel **THE KEY FIX**
-
----
-
-### 2. ⚠️ REQ Parsing Failure (CRITICAL)
-**Problem:** All REQ messages failed with EOF error
-
-**Root Cause:** Filter parser consuming envelope closing bracket
-- `filter.S.Unmarshal` assumed filters were array-wrapped `[{...},{...}]`
-- In REQ envelopes, filters are unwrapped: `"subid",{...},{...}]`
-- Parser consumed the closing `]` meant for the envelope
-- `SkipToTheEnd` couldn't find closing bracket → EOF error
-
-**Solution:** Handle both wrapped and unwrapped filter arrays
-- Detect if filters start with `[` (array-wrapped) or `{` (unwrapped)
-- For unwrapped filters, leave closing `]` for envelope parser
-- For wrapped filters, consume the closing `]` as before
-
-**Files Modified:**
-- `pkg/encoders/filter/filters.go:49-103` - Smart filter parsing **THE KEY FIX**
-
----
-
-### 3. ⚠️ Subscription Drops (CRITICAL)
-**Problem:** Subscriptions stopped receiving events after ~30-60 seconds
-
-**Root Cause:** Receiver channels created but never consumed
-- Channels filled up (32 event buffer)
-- Publisher timed out trying to send
-- Subscriptions removed as "dead"
-
-**Solution:** Per-subscription consumer goroutines (khatru pattern)
-- Each subscription gets dedicated goroutine
-- Continuously reads from receiver channel
-- Forwards events to client via write worker
-- Clean cancellation via context
-
-**Files Modified:**
-- `app/listener.go:45-46` - Added subscription tracking map
-- `app/handle-req.go:644-688` - Consumer goroutines **THE KEY FIX**
-- `app/handle-close.go:29-48` - Proper cancellation
-- `app/handle-websocket.go:136-143` - Cleanup all on disconnect
-
----
-
-### 4. ⚠️ Message Queue Overflow
-**Problem:** Message queue filled up, messages dropped
-```
-⚠️ ws->10.0.0.2 message queue full, dropping message (capacity=100)
-```
-
-**Root Cause:** Messages processed synchronously
-- `HandleMessage` → `HandleReq` can take seconds (database queries)
-- While one message processes, others pile up
-- Queue fills (100 capacity)
-- New messages dropped
-
-**Solution:** Concurrent message processing (khatru pattern)
-```go
-// BEFORE: Synchronous (blocking)
-l.HandleMessage(req.data, req.remote)  // Blocks until done
-
-// AFTER: Concurrent (non-blocking)
-go l.HandleMessage(req.data, req.remote)  // Spawns goroutine
-```
-
-**Files Modified:**
-- `app/listener.go:199` - Added `go` keyword for concurrent processing
-
----
-
-### 5. ⚠️ Test Tool Panic
-**Problem:** Subscription test tool panicked
-```
-panic: repeated read on failed websocket connection
-```
-
-**Root Cause:** Error handling didn't distinguish timeout from fatal errors
-- Timeout errors continued reading
-- Fatal errors continued reading
-- Eventually hit gorilla/websocket's panic
-
-**Solution:** Proper error type detection
-- Check for timeout using type assertion
-- Exit cleanly on fatal errors
-- Limit consecutive timeouts (20 max)
-
-**Files Modified:**
-- `cmd/subscription-test/main.go:124-137` - Better error handling
-
----
-
-## Architecture Changes
-
-### Message Flow (Before → After)
-
-**BEFORE (Broken):**
-```
-WebSocket Read → Queue Message → Process Synchronously (BLOCKS)
-                                       ↓
-                              Queue fills → Drop messages
-
-REQ → Create Receiver Channel → Register → (nothing reads channel)
-                                               ↓
-                                    Events published → Try to send → TIMEOUT
-                                                                         ↓
-                                                              Subscription removed
-```
-
-**AFTER (Fixed - khatru pattern):**
-```
-WebSocket Read → Queue Message → Process Concurrently (NON-BLOCKING)
-                                       ↓
-                              Multiple handlers run in parallel
-
-REQ → Create Receiver Channel → Register → Launch Consumer Goroutine
-                                                    ↓
-                                    Events published → Send to channel (fast)
-                                                    ↓
-                                    Consumer reads → Forward to client (continuous)
-```
-
----
-
-## khatru Patterns Adopted
-
-### 1. Per-Subscription Consumer Goroutines
-```go
-go func() {
-    for {
-        select {
-        case <-subCtx.Done():
-            return  // Clean cancellation
-        case ev := <-receiver:
-            // Forward event to client
-            eventenvelope.NewResultWith(subID, ev).Write(l)
-        }
-    }
-}()
-```
-
-### 2. Concurrent Message Handling
-```go
-// Sequential parsing (in read loop)
-envelope := parser.Parse(message)
-
-// Concurrent handling (in goroutine)
-go handleMessage(envelope)
-```
-
-### 3. Independent Subscription Contexts
-```go
-// Connection context (cancelled on disconnect)
-ctx, cancel := context.WithCancel(serverCtx)
-
-// Subscription context (cancelled on CLOSE or disconnect)
-subCtx, subCancel := context.WithCancel(ctx)
-```
-
-### 4. Write Serialization
-```go
-// Single write worker goroutine per connection
-go func() {
-    for req := range writeChan {
-        conn.WriteMessage(req.MsgType, req.Data)
-    }
-}()
-```
-
----
-
-## Files Modified Summary
-
-| File | Change | Impact |
-|------|--------|--------|
-| `app/publisher.go:32` | Added Receiver field | **Store receiver channels** |
-| `app/publisher.go:125,130` | Store receiver on registration | **Connect publisher to consumers** |
-| `app/publisher.go:242-266` | Send to receiver channel | **Fix event delivery** |
-| `pkg/encoders/filter/filters.go:49-103` | Smart filter parsing | **Fix REQ parsing** |
-| `app/listener.go:45-46` | Added subscription tracking | Track subs for cleanup |
-| `app/listener.go:199` | Concurrent message processing | **Fix queue overflow** |
-| `app/handle-req.go:621-627` | Independent sub contexts | Isolated lifecycle |
-| `app/handle-req.go:644-688` | Consumer goroutines | **Fix subscription drops** |
-| `app/handle-close.go:29-48` | Proper cancellation | Clean sub cleanup |
-| `app/handle-websocket.go:136-143` | Cancel all on disconnect | Clean connection cleanup |
-| `cmd/subscription-test/main.go:124-137` | Better error handling | **Fix test panic** |
-
----
-
-## Performance Impact
-
-### Before (Broken)
-- ❌ REQ messages fail with EOF error
-- ❌ Subscriptions drop after ~30-60 seconds
-- ❌ Message queue fills up under load
-- ❌ Events stop being delivered
-- ❌ Memory leaks (goroutines/channels)
-- ❌ CPU waste on timeout retries
-
-### After (Fixed)
-- ✅ REQ messages parse correctly
-- ✅ Subscriptions stable indefinitely (hours/days)
-- ✅ Message queue never fills up
-- ✅ All events delivered without timeouts
-- ✅ No resource leaks
-- ✅ Efficient goroutine usage
-
-### Metrics
-
-| Metric | Before | After |
-|--------|--------|-------|
-| Subscription lifetime | ~30-60s | Unlimited |
-| Events per subscription | ~32 max | Unlimited |
-| Message processing | Sequential | Concurrent |
-| Queue drops | Common | Never |
-| Goroutines per connection | Leaking | Clean |
-| Memory per subscription | Growing | Stable ~10KB |
-
----
-
-## Testing
-
-### Quick Test (No Events Needed)
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run test
-./subscription-test-simple -duration 120
-```
-
-**Expected:** Subscription stays active for full 120 seconds
-
-### Full Test (With Events)
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run test
-./subscription-test -duration 60 -v
-
-# Terminal 3: Publish events (your method)
-```
-
-**Expected:** All published events received throughout 60 seconds
-
-### Load Test
-```bash
-# Run multiple subscriptions simultaneously
-for i in {1..10}; do
-    ./subscription-test-simple -duration 120 -sub "sub$i" &
-done
-```
-
-**Expected:** All 10 subscriptions stay active with no queue warnings
-
----
-
-## Documentation
-
-- **[PUBLISHER_FIX.md](PUBLISHER_FIX.md)** - Publisher event delivery fix (NEW)
-- **[TEST_NOW.md](TEST_NOW.md)** - Quick testing guide
-- **[MESSAGE_QUEUE_FIX.md](MESSAGE_QUEUE_FIX.md)** - Queue overflow details
-- **[SUBSCRIPTION_STABILITY_FIXES.md](SUBSCRIPTION_STABILITY_FIXES.md)** - Subscription fixes
-- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Comprehensive testing
-- **[QUICK_START.md](QUICK_START.md)** - 30-second overview
-- **[SUMMARY.md](SUMMARY.md)** - Executive summary
-
----
-
-## Build & Deploy
-
-```bash
-# Build everything
-go build -o orly
-go build -o subscription-test ./cmd/subscription-test
-go build -o subscription-test-simple ./cmd/subscription-test-simple
-
-# Verify
-./subscription-test-simple -duration 60
-
-# Deploy
-# Replace existing binary, restart service
-```
-
----
-
-## Backwards Compatibility
-
-✅ **100% Backward Compatible**
-- No wire protocol changes
-- No client changes required
-- No configuration changes
-- No database migrations
-
-Existing clients automatically benefit from improved stability.
-
----
-
-## What to Expect After Deploy
-
-### Positive Indicators (What You'll See)
-```
-✓ subscription X created and goroutine launched
-✓ delivered real-time event Y to subscription X
-✓ subscription delivery QUEUED
-```
-
-### Negative Indicators (Should NOT See)
-```
-✗ subscription delivery TIMEOUT
-✗ removing failed subscriber connection
-✗ message queue full, dropping message
-```
-
----
-
-## Summary
-
-Five critical issues fixed following khatru patterns:
-
-1. **Publisher not delivering events** → Store and use receiver channels
-2. **REQ parsing failure** → Handle both wrapped and unwrapped filter arrays
-3. **Subscription drops** → Per-subscription consumer goroutines
-4. **Message queue overflow** → Concurrent message processing
-5. **Test tool panic** → Proper error handling
-
-**Result:** WebSocket connections and subscriptions now stable indefinitely with proper event delivery and no resource leaks or message drops.
-
-**Status:** ✅ All fixes implemented and building successfully
-**Ready:** For testing and deployment

BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md

@@ -0,0 +1,254 @@
+# Feature Request and Bug Report Protocol
+
+This document describes how to submit effective bug reports and feature requests for ORLY relay. Following these guidelines helps maintainers understand and resolve issues quickly.
+
+## Before Submitting
+
+1. **Search existing issues** - Your issue may already be reported or discussed
+2. **Check documentation** - Review `CLAUDE.md`, `docs/`, and `pkg/*/README.md` files
+3. **Verify with latest version** - Ensure the issue exists in the current release
+4. **Test with default configuration** - Rule out configuration-specific problems
+
+## Bug Reports
+
+### Required Information
+
+**Title**: Concise summary of the problem
+- Good: "Kind 3 events with 8000+ follows truncated on save"
+- Bad: "Events not saving" or "Bug in database"
+
+**Environment**:
+```
+ORLY version: (output of ./orly version)
+OS: (e.g., Ubuntu 24.04, macOS 14.2)
+Go version: (output of go version)
+Database backend: (badger/neo4j/wasmdb)
+```
+
+**Configuration** (relevant settings only):
+```bash
+ORLY_DB_TYPE=badger
+ORLY_POLICY_ENABLED=true
+# Include any non-default settings
+```
+
+**Steps to Reproduce**:
+1. Start relay with configuration X
+2. Connect client and send event Y
+3. Query for event with filter Z
+4. Observe error/unexpected behavior
+
+**Expected Behavior**: What should happen
+
+**Actual Behavior**: What actually happens
+
+**Logs**: Include relevant log output with `ORLY_LOG_LEVEL=debug` or `trace`
+
+### Minimal Reproduction
+
+The most effective bug reports include a minimal reproduction case:
+
+```bash
+# Example: Script that demonstrates the issue
+export ORLY_LOG_LEVEL=debug
+./orly &
+sleep 2
+
+# Send problematic event
+echo '["EVENT", {...}]' | websocat ws://localhost:3334
+
+# Show the failure
+echo '["REQ", "test", {"kinds": [1]}]' | websocat ws://localhost:3334
+```
+
+Or provide a failing test case:
+
+```go
+func TestReproduceBug(t *testing.T) {
+    // Setup
+    db := setupTestDB(t)
+
+    // This should work but fails
+    event := createTestEvent(kind, content)
+    err := db.SaveEvent(ctx, event)
+    require.NoError(t, err)
+
+    // Query returns unexpected result
+    results, err := db.QueryEvents(ctx, filter)
+    assert.Len(t, results, 1) // Fails: got 0
+}
+```
+
+## Feature Requests
+
+### Required Information
+
+**Title**: Clear description of the feature
+- Good: "Add WebSocket compression support (permessage-deflate)"
+- Bad: "Make it faster" or "New feature idea"
+
+**Problem Statement**: What problem does this solve?
+```
+Currently, clients with high-latency connections experience slow sync times
+because event data is transmitted uncompressed. A typical session transfers
+50MB of JSON that could be reduced to ~10MB with compression.
+```
+
+**Proposed Solution**: How should it work?
+```
+Add optional permessage-deflate WebSocket extension support:
+- New config: ORLY_WS_COMPRESSION=true
+- Negotiate compression during WebSocket handshake
+- Apply to messages over configurable threshold (default 1KB)
+```
+
+**Use Case**: Who benefits and how?
+```
+- Mobile clients on cellular connections
+- Users syncing large follow lists
+- Relays with bandwidth constraints
+```
+
+**Alternatives Considered** (optional):
+```
+- Application-level compression: Rejected because it requires client changes
+- HTTP/2: Not applicable for WebSocket connections
+```
+
+### Implementation Notes (optional)
+
+If you have implementation ideas:
+
+```
+Suggested approach:
+1. Add compression config to app/config/config.go
+2. Modify gorilla/websocket upgrader in app/handle-websocket.go
+3. Add compression threshold check before WriteMessage()
+
+Reference: gorilla/websocket has built-in permessage-deflate support
+```
+
+## What Makes Reports Effective
+
+**Do**:
+- Be specific and factual
+- Include version numbers and exact error messages
+- Provide reproducible steps
+- Attach relevant logs (redact sensitive data)
+- Link to related issues or discussions
+- Respond to follow-up questions promptly
+
+**Avoid**:
+- Vague descriptions ("it doesn't work")
+- Multiple unrelated issues in one report
+- Assuming the cause without evidence
+- Demanding immediate fixes
+- Duplicating existing issues
+
+## Issue Labels
+
+When applicable, suggest appropriate labels:
+
+| Label | Use When |
+|-------|----------|
+| `bug` | Something isn't working as documented |
+| `enhancement` | New feature or improvement |
+| `performance` | Speed or resource usage issue |
+| `documentation` | Docs are missing or incorrect |
+| `question` | Clarification needed (not a bug) |
+| `good first issue` | Suitable for new contributors |
+
+## Response Expectations
+
+- **Acknowledgment**: Within a few days
+- **Triage**: Issue labeled and prioritized
+- **Resolution**: Depends on complexity and priority
+
+Complex features may require discussion before implementation. Bug fixes for critical issues are prioritized.
+
+## Following Up
+
+If your issue hasn't received attention:
+
+1. **Check issue status** - It may be labeled or assigned
+2. **Add new information** - If you've discovered more details
+3. **Politely bump** - A single follow-up comment after 2 weeks is appropriate
+4. **Consider contributing** - PRs that fix bugs or implement features are welcome
+
+## Contributing Fixes
+
+If you want to fix a bug or implement a feature yourself:
+
+1. Comment on the issue to avoid duplicate work
+2. Follow the coding patterns in `CLAUDE.md`
+3. Include tests for your changes
+4. Keep PRs focused on a single issue
+5. Reference the issue number in your PR
+
+## Security Issues
+
+**Do not report security vulnerabilities in public issues.**
+
+For security-sensitive bugs:
+- Contact maintainers directly
+- Provide detailed reproduction steps privately
+- Allow reasonable time for a fix before disclosure
+
+## Examples
+
+### Good Bug Report
+
+```markdown
+## WebSocket disconnects after 60 seconds of inactivity
+
+**Environment**:
+- ORLY v0.34.5
+- Ubuntu 22.04
+- Go 1.25.3
+- Badger backend
+
+**Steps to Reproduce**:
+1. Connect to relay: `websocat ws://localhost:3334`
+2. Send subscription: `["REQ", "test", {"kinds": [1], "limit": 1}]`
+3. Wait 60 seconds without sending messages
+4. Observe connection closed
+
+**Expected**: Connection remains open (Nostr relays should maintain persistent connections)
+
+**Actual**: Connection closed with code 1000 after exactly 60 seconds
+
+**Logs** (ORLY_LOG_LEVEL=debug):
+```
+1764783029014485🔎 client timeout, closing connection /app/handle-websocket.go:142
+```
+
+**Possible Cause**: May be related to read deadline not being extended on subscription activity
+```
+
+### Good Feature Request
+
+```markdown
+## Add rate limiting per pubkey
+
+**Problem**:
+A single pubkey can flood the relay with events, consuming storage and
+bandwidth. Currently there's no way to limit per-author submission rate.
+
+**Proposed Solution**:
+Add configurable rate limiting:
+```bash
+ORLY_RATE_LIMIT_EVENTS_PER_MINUTE=60
+ORLY_RATE_LIMIT_BURST=10
+```
+
+When exceeded, return OK false with "rate-limited" message per NIP-20.
+
+**Use Case**:
+- Public relays protecting against spam
+- Community relays with fair-use policies
+- Paid relays enforcing subscription tiers
+
+**Alternatives Considered**:
+- IP-based limiting: Ineffective because users share IPs and use VPNs
+- Global limiting: Punishes all users for one bad actor
+```

CLAUDE.md

@@ -1,395 +1,215 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+ORLY is a high-performance Nostr relay in Go with Badger/Neo4j/WasmDB backends, Svelte web UI, and purego-based secp256k1 crypto.
 
-## Project Overview
+## Quick Reference
 
-ORLY is a high-performance Nostr relay written in Go, designed for personal relays, small communities, and business deployments. It emphasizes low latency, custom cryptography optimizations, and embedded database performance.
-
-**Key Technologies:**
-- **Language**: Go 1.25.3+
-- **Database**: Badger v4 (embedded key-value store)
-- **Cryptography**: Custom p8k library using purego for secp256k1 operations (no CGO)
-- **Web UI**: Svelte frontend embedded in the binary
-- **WebSocket**: gorilla/websocket for Nostr protocol
-- **Performance**: SIMD-accelerated SHA256 and hex encoding
-
-## Build Commands
-
-### Basic Build
 ```bash
-# Build relay binary only
-go build -o orly
-
-# Pure Go build (no CGO) - this is the standard approach
+# Build
 CGO_ENABLED=0 go build -o orly
-```
+./scripts/update-embedded-web.sh  # With web UI
 
-### Build with Web UI
-```bash
-# Recommended: Use the provided script
-./scripts/update-embedded-web.sh
-
-# Manual build
-cd app/web
-bun install
-bun run build
-cd ../../
-go build -o orly
-```
-
-### Development Mode (Web UI Hot Reload)
-```bash
-# Terminal 1: Start relay with dev proxy
-export ORLY_WEB_DISABLE_EMBEDDED=true
-export ORLY_WEB_DEV_PROXY_URL=localhost:5000
-./orly &
-
-# Terminal 2: Start dev server
-cd app/web && bun run dev
-```
-
-## Testing
-
-### Run All Tests
-```bash
-# Standard test run
+# Test
 ./scripts/test.sh
+go test -v -run TestName ./pkg/package
 
-# Or manually with purego setup
-CGO_ENABLED=0 go test ./...
+# Run
+./orly                    # Start relay
+./orly identity           # Show relay pubkey
+./orly version            # Show version
 
-# Note: libsecp256k1.so must be available for crypto tests
-export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$(pwd)/pkg/crypto/p8k"
+# Web UI dev (hot reload)
+ORLY_WEB_DISABLE=true ORLY_WEB_DEV_PROXY_URL=http://localhost:5173 ./orly &
+cd app/web && bun run dev
+
+# NIP-98 HTTP debugging (build: go build -o nurl ./cmd/nurl)
+NOSTR_SECRET_KEY=nsec1... ./nurl https://relay.example.com/api/logs
+NOSTR_SECRET_KEY=nsec1... ./nurl https://relay.example.com/api/logs/clear
+./nurl help  # Show usage
+
+# Vanity npub generator (build: go build -o vainstr ./cmd/vainstr)
+./vainstr mleku end      # Find npub ending with "mleku"
+./vainstr orly begin     # Find npub starting with "orly" (after npub1)
+./vainstr foo contain    # Find npub containing "foo"
+./vainstr --threads 4 xyz end  # Use 4 threads
 ```
 
-### Run Specific Package Tests
-```bash
-# Test database package
-cd pkg/database && go test -v ./...
+## Key Environment Variables
 
-# Test protocol package
-cd pkg/protocol && go test -v ./...
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORLY_PORT` | 3334 | Server port |
+| `ORLY_LOG_LEVEL` | info | trace/debug/info/warn/error |
+| `ORLY_DB_TYPE` | badger | badger/neo4j/wasmdb |
+| `ORLY_POLICY_ENABLED` | false | Enable policy system |
+| `ORLY_ACL_MODE` | none | none/follows/managed |
+| `ORLY_TLS_DOMAINS` | | Let's Encrypt domains |
+| `ORLY_AUTH_TO_WRITE` | false | Require auth for writes |
 
-# Test with specific test function
-go test -v -run TestSaveEvent ./pkg/database
+**Neo4j Memory Tuning** (only when `ORLY_DB_TYPE=neo4j`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORLY_NEO4J_MAX_CONN_POOL` | 25 | Max connections (lower = less memory) |
+| `ORLY_NEO4J_FETCH_SIZE` | 1000 | Records per batch (-1=all) |
+| `ORLY_NEO4J_QUERY_RESULT_LIMIT` | 10000 | Max results per query (0=unlimited) |
+
+See `./orly help` for all options. **All env vars MUST be defined in `app/config/config.go`**.
+
+## Architecture
+
+```
+main.go              → Entry point
+app/
+  server.go          → HTTP/WebSocket server
+  handle-*.go        → Nostr message handlers (EVENT, REQ, AUTH, etc.)
+  config/            → Environment configuration (go-simpler.org/env)
+  web/               → Svelte frontend (embedded via go:embed)
+pkg/
+  database/          → Database interface + Badger implementation
+  neo4j/             → Neo4j backend with WoT extensions
+  wasmdb/            → WebAssembly IndexedDB backend
+  protocol/          → Nostr protocol (ws/, auth/, publish/)
+  encoders/          → Optimized JSON encoding with buffer pools
+  policy/            → Event filtering/validation
+  acl/               → Access control (none/follows/managed)
+cmd/
+  relay-tester/      → Protocol compliance testing
+  benchmark/         → Performance testing
 ```
 
-### Relay Protocol Testing
-```bash
-# Test relay protocol compliance
-go run cmd/relay-tester/main.go -url ws://localhost:3334
+## Critical Rules
 
-# List available tests
-go run cmd/relay-tester/main.go -list
+### 1. Binary-Optimized Tag Storage (MUST READ)
 
-# Run specific test
-go run cmd/relay-tester/main.go -url ws://localhost:3334 -test "Basic Event"
+The nostr library stores `e` and `p` tag values as 33-byte binary (not 64-char hex).
+
+```go
+// WRONG - may be binary garbage
+pubkey := string(tag.T[1])
+pt, err := hex.Dec(string(pTag.Value()))
+
+// CORRECT - always use ValueHex()
+pubkey := string(pTag.ValueHex())           // Returns lowercase hex
+pt, err := hex.Dec(string(pTag.ValueHex()))
+
+// For event.E fields (always binary)
+pubkeyHex := hex.Enc(ev.Pubkey[:])
 ```
 
-### Benchmarking
-```bash
-# Run benchmarks in specific package
-go test -bench=. -benchmem ./pkg/database
+**Always normalize to lowercase hex** when storing in Neo4j to prevent duplicates.
 
-# Crypto benchmarks
-cd pkg/crypto/p8k && make bench
+### 2. Configuration System
+
+- **ALL env vars in `app/config/config.go`** - never use `os.Getenv()` in packages
+- Pass config via structs (e.g., `database.DatabaseConfig`)
+- Use `ORLY_` prefix for all variables
+
+### 3. Interface Design
+
+- **Define interfaces in `pkg/interfaces/<name>/`** - prevents circular deps
+- **Never use interface literals** in type assertions: `.(interface{ Method() })` is forbidden
+- Existing: `acl/`, `neterr/`, `resultiter/`, `store/`, `publisher/`, `typer/`
+
+### 4. Constants
+
+Define named constants for repeated values. No magic numbers/strings.
+
+```go
+// BAD
+if timeout > 30 {
+
+// GOOD
+const DefaultTimeoutSeconds = 30
+if timeout > DefaultTimeoutSeconds {
 ```
 
-## Running the Relay
+### 5. Domain Encapsulation
 
-### Basic Run
-```bash
-# Build and run
-go build -o orly && ./orly
+- Use unexported fields for internal state
+- Provide public API methods (`IsEnabled()`, `CheckPolicy()`)
+- Never change unexported→exported to fix bugs
 
-# With environment variables
-export ORLY_LOG_LEVEL=debug
-export ORLY_PORT=3334
-./orly
+## Database Backends
+
+| Backend | Use Case | Build |
+|---------|----------|-------|
+| **Badger** (default) | Single-instance, embedded | Standard |
+| **Neo4j** | Social graph, WoT queries | `ORLY_DB_TYPE=neo4j` |
+| **WasmDB** | Browser/WebAssembly | `GOOS=js GOARCH=wasm` |
+
+All implement `pkg/database.Database` interface.
+
+## Logging (lol.mleku.dev)
+
+```go
+import "lol.mleku.dev/log"
+import "lol.mleku.dev/chk"
+
+log.T.F("trace: %s", msg)  // T=Trace, D=Debug, I=Info, W=Warn, E=Error, F=Fatal
+if chk.E(err) { return }   // Log + check error
 ```
 
-### Get Relay Identity
-```bash
-# Print relay identity secret and pubkey
-./orly identity
+## Development Workflows
+
+**Add Nostr handler**: Create `app/handle-<type>.go` → add case in `handle-message.go`
+
+**Add database index**: Define in `pkg/database/indexes/` → add migration → update `save-event.go` → add query builder
+
+**Profiling**: `ORLY_PPROF=cpu ./orly` or `ORLY_PPROF_HTTP=true` for :6060
+
+## Commit Format
+
+```
+Fix description in imperative mood (72 chars max)
+
+- Bullet point details
+- More details
+
+Files modified:
+- path/to/file.go: What changed
 ```
 
-### Common Configuration
-```bash
-# TLS with Let's Encrypt
-export ORLY_TLS_DOMAINS=relay.example.com
+## Web UI Libraries
 
-# Admin configuration
-export ORLY_ADMINS=npub1...
+### nsec-crypto.js
 
-# Follows ACL mode
-export ORLY_ACL_MODE=follows
+Secure nsec encryption library at `app/web/src/nsec-crypto.js`. Uses Argon2id + AES-256-GCM.
 
-# Enable sprocket event processing
-export ORLY_SPROCKET_ENABLED=true
+```js
+import { encryptNsec, decryptNsec, isValidNsec, deriveKey } from "./nsec-crypto.js";
 
-# Enable policy system
-export ORLY_POLICY_ENABLED=true
+// Encrypt nsec with password (~3 sec derivation)
+const encrypted = await encryptNsec(nsec, password);
+
+// Decrypt (validates bech32 checksum)
+const nsec = await decryptNsec(encrypted, password);
+
+// Validate nsec format and checksum
+if (isValidNsec(nsec)) { ... }
 ```
 
-## Code Architecture
+**Argon2id parameters**: 4 threads, 8 iterations, 256MB memory, 32-byte output.
 
-### Repository Structure
+**Storage format**: Base64(salt[32] + iv[12] + ciphertext). Validates bech32 on encrypt/decrypt.
 
-**Root Entry Point:**
-- `main.go` - Application entry point with signal handling, profiling setup, and database initialization
-- `app/main.go` - Core relay server initialization and lifecycle management
+## Documentation
 
-**Core Packages:**
+| Topic | Location |
+|-------|----------|
+| Policy config | `docs/POLICY_CONFIGURATION_REFERENCE.md` |
+| Policy guide | `docs/POLICY_USAGE_GUIDE.md` |
+| Neo4j WoT schema | `pkg/neo4j/WOT_SPEC.md` |
+| Neo4j schema changes | `pkg/neo4j/MODIFYING_SCHEMA.md` |
+| Event kinds database | `app/web/src/eventKinds.js` |
+| Nsec encryption | `app/web/src/nsec-crypto.js` |
 
-**`app/`** - HTTP/WebSocket server and handlers
-- `server.go` - Main Server struct and HTTP request routing
-- `handle-*.go` - Nostr protocol message handlers (EVENT, REQ, COUNT, CLOSE, AUTH, DELETE)
-- `handle-websocket.go` - WebSocket connection lifecycle and frame handling
-- `listener.go` - Network listener setup
-- `sprocket.go` - External event processing script manager
-- `publisher.go` - Event broadcast to active subscriptions
-- `payment_processor.go` - NWC integration for subscription payments
-- `blossom.go` - Blob storage service initialization
-- `web.go` - Embedded web UI serving and dev proxy
-- `config/` - Environment variable configuration using go-simpler.org/env
+## Dependencies
 
-**`pkg/database/`** - Badger-based event storage
-- `database.go` - Database initialization with cache tuning
-- `save-event.go` - Event storage with index updates
-- `query-events.go` - Main query execution engine
-- `query-for-*.go` - Specialized query builders for different filter patterns
-- `indexes/` - Index key construction for efficient lookups
-- `export.go` / `import.go` - Event export/import in JSONL format
-- `subscriptions.go` - Active subscription tracking
-- `identity.go` - Relay identity key management
-- `migrations.go` - Database schema migration runner
-
-**`pkg/protocol/`** - Nostr protocol implementation
-- `ws/` - WebSocket message framing and parsing
-- `auth/` - NIP-42 authentication challenge/response
-- `publish/` - Event publisher for broadcasting to subscriptions
-- `relayinfo/` - NIP-11 relay information document
-- `directory/` - Distributed directory service (NIP-XX)
-- `nwc/` - Nostr Wallet Connect client
-- `blossom/` - Blob storage protocol
-
-**`pkg/encoders/`** - Optimized Nostr data encoding/decoding
-- `event/` - Event JSON marshaling/unmarshaling with buffer pooling
-- `filter/` - Filter parsing and validation
-- `bech32encoding/` - npub/nsec/note encoding
-- `hex/` - SIMD-accelerated hex encoding using templexxx/xhex
-- `timestamp/`, `kind/`, `tag/` - Specialized field encoders
-
-**`pkg/crypto/`** - Cryptographic operations
-- `p8k/` - Pure Go secp256k1 using purego (no CGO) to dynamically load libsecp256k1.so
-  - `secp.go` - Dynamic library loading and function binding
-  - `schnorr.go` - Schnorr signature operations (NIP-01)
-  - `ecdh.go` - ECDH for encrypted DMs (NIP-04, NIP-44)
-  - `recovery.go` - Public key recovery from signatures
-  - `libsecp256k1.so` - Pre-compiled secp256k1 library
-- `keys/` - Key derivation and conversion utilities
-- `sha256/` - SIMD-accelerated SHA256 using minio/sha256-simd
-
-**`pkg/acl/`** - Access control systems
-- `acl.go` - ACL registry and interface
-- `follows.go` - Follows-based whitelist (admins + their follows can write)
-- `managed.go` - NIP-86 managed relay with role-based permissions
-- `none.go` - Open relay (no restrictions)
-
-**`pkg/policy/`** - Event filtering and validation policies
-- Policy configuration loaded from `~/.config/ORLY/policy.json`
-- Per-kind size limits, age restrictions, custom scripts
-- See `docs/POLICY_USAGE_GUIDE.md` for configuration examples
-
-**`pkg/sync/`** - Distributed synchronization
-- `cluster_manager.go` - Active replication between relay peers
-- `relay_group_manager.go` - Relay group configuration (NIP-XX)
-- `manager.go` - Distributed directory consensus
-
-**`pkg/spider/`** - Event syncing from other relays
-- `spider.go` - Spider manager for "follows" mode
-- Fetches events from admin relays for followed pubkeys
-
-**`pkg/utils/`** - Shared utilities
-- `atomic/` - Extended atomic operations
-- `interrupt/` - Signal handling and graceful shutdown
-- `apputil/` - Application-level utilities
-
-**Web UI (`app/web/`):**
-- Svelte-based admin interface
-- Embedded in binary via `go:embed`
-- Features: event browser, sprocket management, user admin, settings
-
-**Command-line Tools (`cmd/`):**
-- `relay-tester/` - Nostr protocol compliance testing
-- `benchmark/` - Multi-relay performance comparison
-- `stresstest/` - Load testing tool
-- `aggregator/` - Event aggregation utility
-- `convert/` - Data format conversion
-- `policytest/` - Policy validation testing
-
-### Important Patterns
-
-**Pure Go with Purego:**
-- All builds use `CGO_ENABLED=0`
-- The p8k crypto library uses `github.com/ebitengine/purego` to dynamically load `libsecp256k1.so` at runtime
-- This avoids CGO complexity while maintaining C library performance
-- `libsecp256k1.so` must be in `LD_LIBRARY_PATH` or same directory as binary
-
-**Database Query Pattern:**
-- Filters are analyzed in `get-indexes-from-filter.go` to determine optimal query strategy
-- Different query builders (`query-for-kinds.go`, `query-for-authors.go`, etc.) handle specific filter patterns
-- All queries return event serials (uint64) for efficient joining
-- Final events fetched via `fetch-events-by-serials.go`
-
-**WebSocket Message Flow:**
-1. `handle-websocket.go` accepts connection and spawns goroutine
-2. Incoming frames parsed by `pkg/protocol/ws/`
-3. Routed to handlers: `handle-event.go`, `handle-req.go`, `handle-count.go`, etc.
-4. Events stored via `database.SaveEvent()`
-5. Active subscriptions notified via `publishers.Publish()`
-
-**Configuration System:**
-- Uses `go-simpler.org/env` for struct tags
-- All config in `app/config/config.go` with `ORLY_` prefix
-- Supports XDG directories via `github.com/adrg/xdg`
-- Default data directory: `~/.local/share/ORLY`
-
-**Event Publishing:**
-- `pkg/protocol/publish/` manages publisher registry
-- Each WebSocket connection registers its subscriptions
-- `publishers.Publish(event)` broadcasts to matching subscribers
-- Efficient filter matching without re-querying database
-
-**Embedded Assets:**
-- Web UI built to `app/web/dist/`
-- Embedded via `//go:embed` directive in `app/web.go`
-- Served at root path `/` with API at `/api/*`
-
-## Development Workflow
-
-### Making Changes to Web UI
-1. Edit files in `app/web/src/`
-2. For hot reload: `cd app/web && bun run dev` (with `ORLY_WEB_DISABLE_EMBEDDED=true`)
-3. For production build: `./scripts/update-embedded-web.sh`
-
-### Adding New Nostr Protocol Handlers
-1. Create `app/handle-<message-type>.go`
-2. Add case in `app/handle-message.go` message router
-3. Implement handler following existing patterns
-4. Add tests in `app/<handler>_test.go`
-
-### Adding Database Indexes
-1. Define index in `pkg/database/indexes/`
-2. Add migration in `pkg/database/migrations.go`
-3. Update `save-event.go` to populate index
-4. Add query builder in `pkg/database/query-for-<index>.go`
-5. Update `get-indexes-from-filter.go` to use new index
-
-### Environment Variables for Development
-```bash
-# Verbose logging
-export ORLY_LOG_LEVEL=trace
-export ORLY_DB_LOG_LEVEL=debug
-
-# Enable profiling
-export ORLY_PPROF=cpu
-export ORLY_PPROF_HTTP=true  # Serves on :6060
-
-# Health check endpoint
-export ORLY_HEALTH_PORT=8080
-```
-
-### Profiling
-```bash
-# CPU profiling
-export ORLY_PPROF=cpu
-./orly
-# Profile written on shutdown
-
-# HTTP pprof server
-export ORLY_PPROF_HTTP=true
-./orly
-# Visit http://localhost:6060/debug/pprof/
-
-# Memory profiling
-export ORLY_PPROF=memory
-export ORLY_PPROF_PATH=/tmp/profiles
-```
-
-## Deployment
-
-### Automated Deployment
-```bash
-# Deploy with systemd service
-./scripts/deploy.sh
-```
-
-This script:
-1. Installs Go 1.25.0 if needed
-2. Builds relay with embedded web UI
-3. Installs to `~/.local/bin/orly`
-4. Creates systemd service
-5. Sets capabilities for port 443 binding
-
-### systemd Service Management
-```bash
-# Start/stop/restart
-sudo systemctl start orly
-sudo systemctl stop orly
-sudo systemctl restart orly
-
-# Enable on boot
-sudo systemctl enable orly
-
-# View logs
-sudo journalctl -u orly -f
-```
-
-### Manual Deployment
-```bash
-# Build for production
-./scripts/update-embedded-web.sh
-
-# Or build all platforms
-./scripts/build-all-platforms.sh
-```
-
-## Key Dependencies
-
-- `github.com/dgraph-io/badger/v4` - Embedded database
-- `github.com/gorilla/websocket` - WebSocket server
+- `github.com/dgraph-io/badger/v4` - Badger DB
+- `github.com/neo4j/neo4j-go-driver/v5` - Neo4j
+- `github.com/gorilla/websocket` - WebSocket
+- `github.com/ebitengine/purego` - CGO-free C loading
 - `github.com/minio/sha256-simd` - SIMD SHA256
-- `github.com/templexxx/xhex` - SIMD hex encoding
-- `github.com/ebitengine/purego` - CGO-free C library loading
-- `go-simpler.org/env` - Environment variable configuration
-- `lol.mleku.dev` - Custom logging library
-
-## Testing Guidelines
-
-- Test files use `_test.go` suffix
-- Use `github.com/stretchr/testify` for assertions
-- Database tests require temporary database setup (see `pkg/database/testmain_test.go`)
-- WebSocket tests should use `relay-tester` package
-- Always clean up resources in tests (database, connections, goroutines)
-
-## Performance Considerations
-
-- **Database Caching**: Tune `ORLY_DB_BLOCK_CACHE_MB` and `ORLY_DB_INDEX_CACHE_MB` for workload
-- **Query Optimization**: Add indexes for common filter patterns
-- **Memory Pooling**: Use buffer pools in encoders (see `pkg/encoders/event/`)
-- **SIMD Operations**: Leverage minio/sha256-simd and templexxx/xhex
-- **Goroutine Management**: Each WebSocket connection runs in its own goroutine
-
-## Release Process
-
-1. Update version in `pkg/version/version` file (e.g., v1.2.3)
-2. Create and push tag:
-   ```bash
-   git tag v1.2.3
-   git push origin v1.2.3
-   ```
-3. GitHub Actions workflow builds binaries for multiple platforms
-4. Release created automatically with binaries and checksums
+- `go-simpler.org/env` - Config
+- `lol.mleku.dev` - Logging

CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to ORLY
+
+Thank you for your interest in contributing to ORLY! This document outlines the process for reporting bugs, requesting features, and submitting contributions.
+
+**Canonical Repository:** https://git.mleku.dev/mleku/next.orly.dev
+
+## Issue Reporting Policy
+
+### Before Opening an Issue
+
+1. **Search existing issues** to avoid duplicates
+2. **Check the documentation** in the repository
+3. **Verify your version** - run `./orly version` and ensure you're on a recent release
+4. **Review the CLAUDE.md** file for configuration guidance
+
+### Bug Reports
+
+Use the **Bug Report** template when reporting unexpected behavior. A good bug report includes:
+
+- **Version information** - exact ORLY version from `./orly version`
+- **Database backend** - Badger, Neo4j, or WasmDB
+- **Clear description** - what happened vs. what you expected
+- **Reproduction steps** - detailed steps to trigger the bug
+- **Logs** - relevant log output (use `ORLY_LOG_LEVEL=debug` or `trace`)
+- **Configuration** - relevant environment variables (redact secrets)
+
+#### Log Levels for Debugging
+
+```bash
+export ORLY_LOG_LEVEL=trace   # Most verbose
+export ORLY_LOG_LEVEL=debug   # Development debugging
+export ORLY_LOG_LEVEL=info    # Default
+```
+
+### Feature Requests
+
+Use the **Feature Request** template when suggesting new functionality. A good feature request includes:
+
+- **Problem statement** - what problem does this solve?
+- **Proposed solution** - specific description of desired behavior
+- **Alternatives considered** - workarounds you've tried
+- **Related NIP** - if this implements a Nostr protocol specification
+- **Impact assessment** - is this a minor tweak or major change?
+
+#### Feature Categories
+
+- **Protocol** - NIP implementations and Nostr protocol features
+- **Database** - Storage backends, indexing, query optimization
+- **Performance** - Caching, SIMD operations, memory optimization
+- **Policy** - Access control, event filtering, validation
+- **Web UI** - Admin interface improvements
+- **Operations** - Deployment, monitoring, systemd integration
+
+## Code Contributions
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://git.mleku.dev/mleku/next.orly.dev.git
+cd next.orly.dev
+
+# Build
+CGO_ENABLED=0 go build -o orly
+
+# Run tests
+./scripts/test.sh
+
+# Build with web UI
+./scripts/update-embedded-web.sh
+```
+
+### Pull Request Guidelines
+
+1. **One feature/fix per PR** - keep changes focused
+2. **Write tests** - for new functionality and bug fixes
+3. **Follow existing patterns** - match the code style of surrounding code
+4. **Update documentation** - if your change affects configuration or behavior
+5. **Test your changes** - run `./scripts/test.sh` before submitting
+
+### Commit Message Format
+
+```
+Short summary (72 chars max, imperative mood)
+
+- Bullet point describing change 1
+- Bullet point describing change 2
+
+Files modified:
+- path/to/file1.go: Description of change
+- path/to/file2.go: Description of change
+```
+
+## Communication
+
+- **Issues:** https://git.mleku.dev/mleku/next.orly.dev/issues
+- **Documentation:** https://git.mleku.dev/mleku/next.orly.dev
+
+## License
+
+By contributing to ORLY, you agree that your contributions will be licensed under the same license as the project.

DDD_ANALYSIS.md

@@ -0,0 +1,816 @@
+# Domain-Driven Design Analysis: ORLY Relay
+
+This document provides a comprehensive Domain-Driven Design (DDD) analysis of the ORLY Nostr relay codebase, evaluating its alignment with DDD principles and identifying opportunities for improvement.
+
+---
+
+## Key Recommendations Summary
+
+| # | Recommendation | Impact | Effort | Status |
+|---|----------------|--------|--------|--------|
+| 1 | [Formalize Domain Events](#1-formalize-domain-events) | High | Medium | Pending |
+| 2 | [Strengthen Aggregate Boundaries](#2-strengthen-aggregate-boundaries) | High | Medium | Partial |
+| 3 | [Extract Application Services](#3-extract-application-services) | Medium | High | Pending |
+| 4 | [Establish Ubiquitous Language Glossary](#4-establish-ubiquitous-language-glossary) | Medium | Low | Pending |
+| 5 | [Add Domain-Specific Error Types](#5-add-domain-specific-error-types) | Medium | Low | Pending |
+| 6 | [Enforce Value Object Immutability](#6-enforce-value-object-immutability) | Low | Low | **Addressed** |
+| 7 | [Document Context Map](#7-document-context-map) | Medium | Low | **This Document** |
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Strategic Design Analysis](#strategic-design-analysis)
+   - [Bounded Contexts](#bounded-contexts)
+   - [Context Map](#context-map)
+   - [Subdomain Classification](#subdomain-classification)
+3. [Tactical Design Analysis](#tactical-design-analysis)
+   - [Entities](#entities)
+   - [Value Objects](#value-objects)
+   - [Aggregates](#aggregates)
+   - [Repositories](#repositories)
+   - [Domain Services](#domain-services)
+   - [Domain Events](#domain-events)
+4. [Anti-Patterns Identified](#anti-patterns-identified)
+5. [Detailed Recommendations](#detailed-recommendations)
+6. [Implementation Checklist](#implementation-checklist)
+7. [Appendix: File References](#appendix-file-references)
+
+---
+
+## Executive Summary
+
+ORLY demonstrates **mature DDD adoption** for a system of its complexity. The codebase exhibits clear bounded context separation, proper repository patterns with multiple backend implementations, and well-designed interface segregation that prevents circular dependencies.
+
+**Strengths:**
+- Clear separation between `app/` (application layer) and `pkg/` (domain/infrastructure)
+- Repository pattern with three interchangeable backends (Badger, Neo4j, WasmDB)
+- Interface-based ACL system with pluggable implementations (None, Follows, Managed)
+- Per-connection aggregate isolation in `Listener`
+- Strong use of Go interfaces for dependency inversion
+- **New:** Immutable `EventRef` value object alongside legacy `IdPkTs`
+- **New:** Comprehensive protocol extensions (Blossom, Graph Queries, NIP-43, NIP-86)
+- **New:** Distributed sync with cluster replication support
+
+**Areas for Improvement:**
+- Domain events are implicit rather than explicit types
+- Some aggregates expose mutable state via public fields
+- Handler methods mix application orchestration with domain logic
+- Ubiquitous language is partially documented
+
+**Overall DDD Maturity Score: 7.5/10** (improved from 7/10)
+
+---
+
+## Strategic Design Analysis
+
+### Bounded Contexts
+
+ORLY organizes code into distinct bounded contexts, each with its own model and language:
+
+#### 1. Event Storage Context (`pkg/database/`)
+- **Responsibility:** Persistent storage of Nostr events with indexing and querying
+- **Key Abstractions:** `Database` interface (109 lines), `Subscription`, `Payment`, `NIP43Membership`
+- **Implementations:** Badger (embedded), Neo4j (graph), WasmDB (browser)
+- **File:** `pkg/database/interface.go:17-109`
+
+#### 2. Access Control Context (`pkg/acl/`)
+- **Responsibility:** Authorization decisions for read/write operations
+- **Key Abstractions:** `I` interface, `Registry`, access levels (none/read/write/admin/owner)
+- **Implementations:** `None`, `Follows`, `Managed`
+- **Files:** `pkg/acl/acl.go`, `pkg/interfaces/acl/acl.go:21-40`
+
+#### 3. Event Policy Context (`pkg/policy/`)
+- **Responsibility:** Event filtering, validation, rate limiting rules, follows-based whitelisting
+- **Key Abstractions:** `Rule`, `Kinds`, `P` (PolicyManager)
+- **Invariants:** Whitelist/blacklist precedence, size limits, tag requirements, protected events
+- **File:** `pkg/policy/policy.go` (extensive, ~1000 lines)
+
+#### 4. Connection Management Context (`app/`)
+- **Responsibility:** WebSocket lifecycle, message routing, authentication, flow control
+- **Key Abstractions:** `Listener`, `Server`, message handlers, `messageRequest`
+- **File:** `app/listener.go:24-52`
+
+#### 5. Protocol Extensions Context (`pkg/protocol/`)
+- **Responsibility:** NIP implementations beyond core protocol
+- **Subcontexts:**
+  - **NIP-43 Membership** (`pkg/protocol/nip43/`): Invite-based access control
+  - **Graph Queries** (`pkg/protocol/graph/`): BFS traversal for follows/followers/threads
+  - **NWC Payments** (`pkg/protocol/nwc/`): Nostr Wallet Connect integration
+  - **Blossom** (`pkg/protocol/blossom/`): BUD protocol definitions
+  - **Directory** (`pkg/protocol/directory/`): Relay directory client
+
+#### 6. Blob Storage Context (`pkg/blossom/`)
+- **Responsibility:** Binary blob storage following BUD specifications
+- **Key Abstractions:** `Server`, `Storage`, `Blob`, `BlobMeta`
+- **Invariants:** SHA-256 hash integrity, MIME type validation, quota enforcement
+- **Files:** `pkg/blossom/server.go`, `pkg/blossom/storage.go`
+
+#### 7. Rate Limiting Context (`pkg/ratelimit/`)
+- **Responsibility:** Adaptive throttling based on system load using PID controller
+- **Key Abstractions:** `Limiter`, `Config`, `OperationType` (Read/Write)
+- **Integration:** Memory pressure from database backends via `loadmonitor` interface
+- **File:** `pkg/ratelimit/limiter.go`
+
+#### 8. Distributed Sync Context (`pkg/sync/`)
+- **Responsibility:** Federation and replication between relay peers
+- **Key Abstractions:** `Manager`, `ClusterManager`, `RelayGroupManager`, `NIP11Cache`
+- **Integration:** Serial-number based sync protocol, NIP-11 peer discovery
+- **Files:** `pkg/sync/manager.go`, `pkg/sync/cluster.go`, `pkg/sync/relaygroup.go`
+
+#### 9. Spider Context (`pkg/spider/`)
+- **Responsibility:** Syncing events from admin relays for followed pubkeys
+- **Key Abstractions:** `Spider`, `RelayConnection`, `DirectorySpider`
+- **Integration:** Batch subscriptions, rate limit backoff, blackout periods
+- **File:** `pkg/spider/spider.go`
+
+### Context Map
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Connection Management (app/)                          │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
+│  │   Server    │───▶│  Listener   │───▶│  Handlers   │◀──▶│  Publishers │   │
+│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘   │
+└────────┬────────────────────┬────────────────────┬──────────────────────────┘
+         │                    │                    │
+         │ [Conformist]       │ [Customer-Supplier]│ [Customer-Supplier]
+         ▼                    ▼                    ▼
+┌────────────────┐   ┌────────────────┐   ┌────────────────┐
+│  Access Control│   │  Event Storage │   │  Event Policy  │
+│   (pkg/acl/)   │   │ (pkg/database/)│   │  (pkg/policy/) │
+│                │   │                │   │                │
+│  Registry ◀────┼───┼────Conformist──┼───┼─▶ Manager      │
+└────────────────┘   └────────────────┘   └────────────────┘
+         │                    │                    │
+         │                    │ [Shared Kernel]    │
+         │                    ▼                    │
+         │           ┌────────────────┐            │
+         │           │  Event Entity  │            │
+         │           │(git.mleku.dev/ │◀───────────┘
+         │           │ mleku/nostr)   │
+         │           └────────────────┘
+         │                    │
+         │ [Anti-Corruption]  │ [Customer-Supplier]
+         ▼                    ▼
+┌────────────────┐   ┌────────────────┐   ┌────────────────┐
+│  Rate Limiting │   │   Protocol     │   │  Blob Storage  │
+│ (pkg/ratelimit)│   │   Extensions   │   │  (pkg/blossom) │
+│                │   │ (pkg/protocol/)│   │                │
+└────────────────┘   └────────────────┘   └────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        ▼                    ▼                    ▼
+┌────────────────┐   ┌────────────────┐   ┌────────────────┐
+│  Distributed   │   │    Spider      │   │ Graph Queries  │
+│     Sync       │   │   (pkg/spider) │   │(pkg/protocol/  │
+│  (pkg/sync/)   │   │                │   │     graph/)    │
+└────────────────┘   └────────────────┘   └────────────────┘
+```
+
+**Integration Patterns Identified:**
+
+| Upstream | Downstream | Pattern | Notes |
+|----------|------------|---------|-------|
+| nostr library | All contexts | Shared Kernel | Event, Filter, Tag types |
+| Database | ACL, Policy, Blossom | Customer-Supplier | Query for follow lists, permissions, blob storage |
+| Policy | Handlers, Sync | Conformist | All respect policy decisions |
+| ACL | Handlers, Blossom | Conformist | Handlers/Blossom respect access levels |
+| Rate Limit | Database | Anti-Corruption | Load monitor abstraction |
+| Sync | Database, Policy | Customer-Supplier | Serial-based event replication |
+
+### Subdomain Classification
+
+| Subdomain | Type | Justification |
+|-----------|------|---------------|
+| Event Storage | **Core** | Central to relay's value proposition |
+| Access Control | **Core** | Key differentiator (WoT, follows-based, managed) |
+| Event Policy | **Core** | Enables complex filtering rules |
+| Graph Queries | **Core** | Unique social graph traversal capabilities |
+| NIP-43 Membership | **Core** | Unique invite-based access model |
+| Blob Storage (Blossom) | **Core** | Media hosting differentiator |
+| Connection Management | **Supporting** | Standard WebSocket infrastructure |
+| Rate Limiting | **Supporting** | Operational concern with PID controller |
+| Distributed Sync | **Supporting** | Infrastructure for federation |
+| Spider | **Supporting** | Data aggregation from external relays |
+
+---
+
+## Tactical Design Analysis
+
+### Entities
+
+Entities are objects with identity that persists across state changes.
+
+#### Listener (Connection Entity)
+```go
+// app/listener.go:24-52
+type Listener struct {
+    conn             *websocket.Conn      // Identity: connection handle
+    challenge        atomicutils.Bytes    // Auth challenge state
+    authedPubkey     atomicutils.Bytes    // Authenticated identity
+    subscriptions    map[string]context.CancelFunc
+    messageQueue     chan messageRequest  // Async message processing
+    droppedMessages  atomic.Int64         // Flow control counter
+    // ... more fields
+}
+```
+- **Identity:** WebSocket connection pointer
+- **Lifecycle:** Created on connect, destroyed on disconnect
+- **Invariants:** Only one authenticated pubkey per connection; AUTH processed synchronously
+
+#### InviteCode (NIP-43 Entity)
+```go
+// pkg/protocol/nip43/types.go:26-31
+type InviteCode struct {
+    Code      string      // Identity: unique code
+    ExpiresAt time.Time
+    UsedBy    []byte      // Tracks consumption
+    CreatedAt time.Time
+}
+```
+- **Identity:** Unique code string
+- **Lifecycle:** Created → Valid → Used/Expired
+- **Invariants:** Cannot be reused once consumed
+
+#### Subscription (Payment Entity)
+```go
+// pkg/database/interface.go (implied by methods)
+// GetSubscription, ExtendSubscription, RecordPayment
+```
+- **Identity:** Pubkey
+- **Lifecycle:** Trial → Active → Expired
+- **Invariants:** Can only extend if not expired
+
+#### Blob (Blossom Entity)
+```go
+// pkg/blossom/blob.go (implied)
+type BlobMeta struct {
+    SHA256    string    // Identity: content-addressable
+    Size      int64
+    Type      string    // MIME type
+    Uploaded  time.Time
+    Owner     []byte    // Uploader pubkey
+}
+```
+- **Identity:** SHA-256 hash
+- **Lifecycle:** Uploaded → Active → Deleted
+- **Invariants:** Hash must match content; owner can delete
+
+### Value Objects
+
+Value objects are immutable and defined by their attributes, not identity.
+
+#### EventRef (Immutable Event Reference) - **NEW**
+```go
+// pkg/interfaces/store/store_interface.go:99-107
+type EventRef struct {
+    id  ntypes.EventID // 32 bytes
+    pub ntypes.Pubkey  // 32 bytes
+    ts  int64          // 8 bytes
+    ser uint64         // 8 bytes
+}
+```
+- **Equality:** By all fields (fixed-size arrays)
+- **Immutability:** Unexported fields, accessor methods return copies
+- **Size:** 80 bytes, cache-line friendly, stack-allocated
+
+#### IdPkTs (Legacy Event Reference)
+```go
+// pkg/interfaces/store/store_interface.go:67-72
+type IdPkTs struct {
+    Id  []byte   // Event ID
+    Pub []byte   // Pubkey
+    Ts  int64    // Timestamp
+    Ser uint64   // Serial number
+}
+```
+- **Equality:** By all fields
+- **Issue:** Mutable slices (use `ToEventRef()` for immutable version)
+- **Migration:** Has `ToEventRef()` and accessors `IDFixed()`, `PubFixed()`
+
+#### Kinds (Policy Specification)
+```go
+// pkg/policy/policy.go:58-63
+type Kinds struct {
+    Whitelist []int `json:"whitelist,omitempty"`
+    Blacklist []int `json:"blacklist,omitempty"`
+}
+```
+- **Equality:** By whitelist/blacklist contents
+- **Semantics:** Whitelist takes precedence over blacklist
+
+#### Rule (Policy Rule)
+```go
+// pkg/policy/policy.go:75-180
+type Rule struct {
+    Description           string
+    WriteAllow           []string
+    WriteDeny            []string
+    ReadFollowsWhitelist []string
+    WriteFollowsWhitelist []string
+    MaxExpiryDuration    string
+    SizeLimit            *int64
+    ContentLimit         *int64
+    Privileged           bool
+    ProtectedRequired    bool
+    ReadAllowPermissive  bool
+    WriteAllowPermissive bool
+    // ... binary caches
+}
+```
+- **Complexity:** 25+ fields, decomposition candidate
+- **Binary caches:** Performance optimization for hex→binary conversion
+
+#### WriteRequest (Message Value)
+```go
+// pkg/protocol/publish/types.go
+type WriteRequest struct {
+    Data      []byte
+    MsgType   int
+    IsControl bool
+    IsPing    bool
+    Deadline  time.Time
+}
+```
+
+### Aggregates
+
+Aggregates are clusters of entities/value objects with consistency boundaries.
+
+#### Listener Aggregate
+- **Root:** `Listener`
+- **Members:** Subscriptions map, auth state, write channel, message queue
+- **Boundary:** Per-connection isolation
+- **Invariants:**
+  - Subscriptions must exist before receiving matching events
+  - AUTH must complete before other messages check authentication
+  - Message processing uses RWMutex for pause/resume during policy updates
+
+```go
+// app/listener.go:226-249 - Aggregate consistency enforcement
+l.authProcessing.Lock()
+if isAuthMessage {
+    // Process AUTH synchronously while holding lock
+    l.HandleMessage(req.data, req.remote)
+    l.authProcessing.Unlock()
+} else {
+    l.authProcessing.Unlock()
+    // Process concurrently
+}
+```
+
+#### Event Aggregate (External)
+- **Root:** `event.E` (from nostr library)
+- **Members:** Tags, signature, content
+- **Invariants:**
+  - ID must match computed hash
+  - Signature must be valid
+  - Timestamp must be within bounds (configurable per-kind)
+- **Validation:** `app/handle-event.go`
+
+#### InviteCode Aggregate
+- **Root:** `InviteCode`
+- **Members:** Code, expiry, usage tracking
+- **Invariants:**
+  - Code uniqueness
+  - Single-use enforcement
+  - Expiry validation
+
+#### Blossom Blob Aggregate
+- **Root:** `BlobMeta`
+- **Members:** Content data, metadata, owner
+- **Invariants:**
+  - SHA-256 integrity
+  - Size limits
+  - MIME type restrictions
+  - Owner-only deletion
+
+### Repositories
+
+The Repository pattern abstracts persistence for aggregate roots.
+
+#### Database Interface (Primary Repository)
+```go
+// pkg/database/interface.go:17-109
+type Database interface {
+    // Core lifecycle
+    Path() string
+    Init(path string) error
+    Sync() error
+    Close() error
+    Ready() <-chan struct{}
+
+    // Event persistence (30+ methods)
+    SaveEvent(c context.Context, ev *event.E) (exists bool, err error)
+    QueryEvents(c context.Context, f *filter.F) (evs event.S, err error)
+    DeleteEvent(c context.Context, eid []byte) error
+
+    // Subscription management
+    GetSubscription(pubkey []byte) (*Subscription, error)
+    ExtendSubscription(pubkey []byte, days int) error
+
+    // NIP-43 membership
+    AddNIP43Member(pubkey []byte, inviteCode string) error
+    IsNIP43Member(pubkey []byte) (isMember bool, err error)
+
+    // Blossom integration
+    ExtendBlossomSubscription(pubkey []byte, tier string, storageMB int64, daysExtended int) error
+    GetBlossomStorageQuota(pubkey []byte) (quotaMB int64, err error)
+
+    // Query cache
+    GetCachedJSON(f *filter.F) ([][]byte, bool)
+    CacheMarshaledJSON(f *filter.F, marshaledJSON [][]byte)
+}
+```
+
+**Repository Implementations:**
+1. **Badger** (`pkg/database/database.go`): Embedded key-value store
+2. **Neo4j** (`pkg/neo4j/`): Graph database for social queries
+3. **WasmDB** (`pkg/wasmdb/`): Browser IndexedDB for WASM builds
+
+**Interface Segregation:**
+```go
+// pkg/interfaces/store/store_interface.go:21-38
+type I interface {
+    Pather
+    io.Closer
+    Wiper
+    Querier      // QueryForIds
+    Querent      // QueryEvents
+    Deleter      // DeleteEvent
+    Saver        // SaveEvent
+    Importer
+    Exporter
+    Syncer
+    LogLeveler
+    EventIdSerialer
+    Initer
+    SerialByIder
+}
+```
+
+### Domain Services
+
+Domain services encapsulate logic that doesn't belong to any single entity.
+
+#### ACL Registry (Access Decision Service)
+```go
+// pkg/acl/acl.go:40-48
+func (s *S) GetAccessLevel(pub []byte, address string) (level string)
+func (s *S) CheckPolicy(ev *event.E) (allowed bool, err error)
+func (s *S) AddFollow(pub []byte)
+```
+- Delegates to active ACL implementation
+- Stateless decision based on pubkey and IP
+- Optional `PolicyChecker` interface for custom validation
+
+#### Policy Manager (Event Validation Service)
+```go
+// pkg/policy/policy.go (P type)
+// CheckPolicy evaluates rule chains, scripts, whitelist/blacklist logic
+// Supports per-kind rules with follows-based whitelisting
+```
+- Complex rule evaluation logic
+- Script execution for custom validation
+- Binary cache optimization for pubkey comparisons
+
+#### InviteManager (Invite Lifecycle Service)
+```go
+// pkg/protocol/nip43/types.go:34-109
+type InviteManager struct {
+    codes  map[string]*InviteCode
+    expiry time.Duration
+}
+func (im *InviteManager) GenerateCode() (code string, err error)
+func (im *InviteManager) ValidateAndConsume(code string, pubkey []byte) (bool, string)
+```
+- Manages invite code lifecycle
+- Thread-safe with mutex protection
+
+#### Graph Executor (Query Execution Service)
+```go
+// pkg/protocol/graph/executor.go:56-60
+type Executor struct {
+    db           GraphDatabase
+    relaySigner  signer.I
+    relayPubkey  []byte
+}
+func (e *Executor) Execute(q *Query) (*event.E, error)
+```
+- BFS traversal for follows/followers/threads
+- Generates relay-signed ephemeral response events
+
+#### Rate Limiter (Throttling Service)
+```go
+// pkg/ratelimit/limiter.go
+type Limiter struct { ... }
+func (l *Limiter) Wait(ctx context.Context, op OperationType) error
+```
+- PID controller-based adaptive throttling
+- Separate setpoints for read/write operations
+- Emergency mode with hysteresis
+
+### Domain Events
+
+**Current State:** Domain events are implicit in message flow, not explicit types.
+
+**Implicit Events Identified:**
+
+| Event | Trigger | Effect |
+|-------|---------|--------|
+| EventPublished | `SaveEvent()` success | `publishers.Deliver()` |
+| EventDeleted | Kind 5 processing | Cascade delete targets |
+| UserAuthenticated | AUTH envelope accepted | `authedPubkey` set |
+| SubscriptionCreated | REQ envelope | Query + stream setup |
+| MembershipAdded | NIP-43 join request | ACL update, kind 8000 event |
+| MembershipRemoved | NIP-43 leave request | ACL update, kind 8001 event |
+| PolicyUpdated | Policy config event | `messagePauseMutex.Lock()` |
+| BlobUploaded | Blossom PUT success | Quota updated |
+| BlobDeleted | Blossom DELETE | Quota released |
+
+---
+
+## Anti-Patterns Identified
+
+### 1. Large Handler Methods (Partial Anemic Domain Model)
+
+**Location:** `app/handle-event.go` (600+ lines)
+
+**Issue:** The event handling contains:
+- Input validation (lowercase hex, JSON structure)
+- Policy checking
+- ACL verification
+- Signature verification
+- Persistence
+- Event delivery
+- Special case handling (delete, ephemeral, NIP-43, NIP-86)
+
+**Impact:** Difficult to test, maintain, and understand. Business rules are embedded in orchestration code.
+
+### 2. Mutable Value Object Fields (Partially Addressed)
+
+**Location:** `pkg/interfaces/store/store_interface.go:67-72`
+
+```go
+type IdPkTs struct {
+    Id  []byte   // Mutable slice
+    Pub []byte   // Mutable slice
+    Ts  int64
+    Ser uint64
+}
+```
+
+**Mitigation:** New `EventRef` type with unexported fields provides immutable alternative.
+Use `ToEventRef()` method for safe conversion.
+
+### 3. Global Singleton Registry
+
+**Location:** `pkg/acl/acl.go:10`
+
+```go
+var Registry = &S{}
+```
+
+**Impact:** Global state makes testing difficult and hides dependencies. Should be injected.
+
+### 4. Missing Domain Events
+
+**Impact:** Side effects are coupled to primary operations. Adding new behaviors (logging, analytics, notifications) requires modifying core handlers.
+
+### 5. Oversized Rule Value Object
+
+**Location:** `pkg/policy/policy.go:75-180`
+
+The `Rule` struct has 25+ fields with binary caches, suggesting decomposition into:
+- `AccessRule` (allow/deny lists, follows whitelists)
+- `SizeRule` (limits)
+- `TimeRule` (expiry, age)
+- `ValidationRule` (tags, regex, protected)
+
+---
+
+## Detailed Recommendations
+
+### 1. Formalize Domain Events
+
+**Problem:** Side effects are tightly coupled to primary operations.
+
+**Solution:** Create explicit domain event types and a simple event dispatcher.
+
+```go
+// pkg/domain/events/events.go
+package events
+
+type DomainEvent interface {
+    OccurredAt() time.Time
+    AggregateID() []byte
+}
+
+type EventPublished struct {
+    EventID   []byte
+    Pubkey    []byte
+    Kind      int
+    Timestamp time.Time
+}
+
+type MembershipGranted struct {
+    Pubkey     []byte
+    InviteCode string
+    Timestamp  time.Time
+}
+
+type BlobUploaded struct {
+    SHA256    string
+    Owner     []byte
+    Size      int64
+    Timestamp time.Time
+}
+```
+
+### 2. Strengthen Aggregate Boundaries
+
+**Problem:** Aggregate internals are exposed via public fields.
+
+**Solution:** The Listener already uses behavior methods well. Extend pattern:
+
+```go
+func (l *Listener) IsAuthenticated() bool {
+    return len(l.authedPubkey.Load()) > 0
+}
+
+func (l *Listener) AuthenticatedPubkey() []byte {
+    return l.authedPubkey.Load()
+}
+```
+
+### 3. Extract Application Services
+
+**Problem:** Handler methods contain mixed concerns.
+
+**Solution:** Extract domain logic into focused application services.
+
+```go
+// pkg/application/event_service.go
+type EventService struct {
+    db            database.Database
+    policyMgr     *policy.P
+    aclRegistry   *acl.S
+    eventPublisher EventPublisher
+}
+
+func (s *EventService) ProcessIncomingEvent(ctx context.Context, ev *event.E, authedPubkey []byte) (*EventResult, error)
+```
+
+### 4. Establish Ubiquitous Language Glossary
+
+**Problem:** Terminology is inconsistent across the codebase.
+
+**Current Inconsistencies:**
+- "subscription" (payment) vs "subscription" (REQ filter)
+- "pub" vs "pubkey" vs "author"
+- "spider" vs "sync" for relay federation
+
+**Solution:** Maintain a `GLOSSARY.md`:
+
+```markdown
+# ORLY Ubiquitous Language
+
+| Term | Definition | Code Symbol |
+|------|------------|-------------|
+| Event | A signed Nostr message | `event.E` |
+| Relay | This server | `Server` |
+| Connection | WebSocket session | `Listener` |
+| Filter | Query criteria for events | `filter.F` |
+| **Event Subscription** | Active filter receiving events | `subscriptions map` |
+| **Payment Subscription** | Paid access tier | `database.Subscription` |
+| Access Level | Permission tier | `acl.Level` |
+| Policy | Event validation rules | `policy.Rule` |
+| Blob | Binary content (images, media) | `blossom.BlobMeta` |
+| Spider | Event aggregator from external relays | `spider.Spider` |
+| Sync | Peer-to-peer replication | `sync.Manager` |
+```
+
+### 5. Add Domain-Specific Error Types
+
+**Problem:** Errors are strings or generic types.
+
+**Solution:** Create typed domain errors in `pkg/interfaces/neterr/` pattern:
+
+```go
+var (
+    ErrEventInvalid       = &DomainError{Code: "EVENT_INVALID"}
+    ErrEventBlocked       = &DomainError{Code: "EVENT_BLOCKED"}
+    ErrAuthRequired       = &DomainError{Code: "AUTH_REQUIRED"}
+    ErrQuotaExceeded      = &DomainError{Code: "QUOTA_EXCEEDED"}
+    ErrInviteCodeInvalid  = &DomainError{Code: "INVITE_INVALID"}
+    ErrBlobTooLarge       = &DomainError{Code: "BLOB_TOO_LARGE"}
+)
+```
+
+### 6. Enforce Value Object Immutability - **ADDRESSED**
+
+The `EventRef` type now provides an immutable alternative:
+
+```go
+// pkg/interfaces/store/store_interface.go:99-153
+type EventRef struct {
+    id  ntypes.EventID // unexported
+    pub ntypes.Pubkey  // unexported
+    ts  int64
+    ser uint64
+}
+
+func (r EventRef) ID() ntypes.EventID { return r.id }   // Returns copy
+func (r EventRef) IDHex() string { return r.id.Hex() }
+func (i *IdPkTs) ToEventRef() EventRef                  // Migration path
+```
+
+### 7. Document Context Map - **THIS DOCUMENT**
+
+The context map is now documented in this file with integration patterns.
+
+---
+
+## Implementation Checklist
+
+### Currently Satisfied
+
+- [x] Bounded contexts identified with clear boundaries
+- [x] Repositories abstract persistence for aggregate roots
+- [x] Multiple repository implementations (Badger/Neo4j/WasmDB)
+- [x] Interface segregation prevents circular dependencies
+- [x] Configuration centralized (`app/config/config.go`)
+- [x] Per-connection aggregate isolation
+- [x] Access control as pluggable strategy pattern
+- [x] Value objects have immutable alternative (`EventRef`)
+- [x] Context map documented
+
+### Needs Attention
+
+- [ ] Ubiquitous language documented and used consistently
+- [ ] Domain events capture important state changes (explicit types)
+- [ ] Entities have behavior, not just data (more encapsulation)
+- [ ] No business logic in application services (handler decomposition)
+- [ ] No infrastructure concerns in domain layer
+
+---
+
+## Appendix: File References
+
+### Core Domain Files
+
+| File | Purpose |
+|------|---------|
+| `pkg/database/interface.go` | Repository interface (109 lines) |
+| `pkg/interfaces/acl/acl.go` | ACL interface definition with PolicyChecker |
+| `pkg/interfaces/store/store_interface.go` | Store sub-interfaces, IdPkTs, EventRef |
+| `pkg/policy/policy.go` | Policy rules and evaluation (~1000 lines) |
+| `pkg/protocol/nip43/types.go` | NIP-43 invite management |
+| `pkg/protocol/graph/executor.go` | Graph query execution |
+
+### Application Layer Files
+
+| File | Purpose |
+|------|---------|
+| `app/server.go` | HTTP/WebSocket server setup (1240 lines) |
+| `app/listener.go` | Connection aggregate (297 lines) |
+| `app/handle-event.go` | EVENT message handler |
+| `app/handle-req.go` | REQ message handler |
+| `app/handle-auth.go` | AUTH message handler |
+| `app/handle-nip43.go` | NIP-43 membership handlers |
+| `app/handle-nip86.go` | NIP-86 management handlers |
+| `app/handle-policy-config.go` | Policy configuration events |
+
+### Infrastructure Files
+
+| File | Purpose |
+|------|---------|
+| `pkg/database/database.go` | Badger implementation |
+| `pkg/neo4j/` | Neo4j implementation |
+| `pkg/wasmdb/` | WasmDB implementation |
+| `pkg/blossom/server.go` | Blossom blob storage server |
+| `pkg/ratelimit/limiter.go` | PID-based rate limiting |
+| `pkg/sync/manager.go` | Distributed sync manager |
+| `pkg/sync/cluster.go` | Cluster replication |
+| `pkg/spider/spider.go` | Event spider/aggregator |
+
+### Interface Packages
+
+| Package | Purpose |
+|---------|---------|
+| `pkg/interfaces/acl/` | ACL abstraction |
+| `pkg/interfaces/loadmonitor/` | Load monitoring abstraction |
+| `pkg/interfaces/neterr/` | Network error types |
+| `pkg/interfaces/pid/` | PID controller interface |
+| `pkg/interfaces/policy/` | Policy interface |
+| `pkg/interfaces/publisher/` | Event publisher interface |
+| `pkg/interfaces/resultiter/` | Result iterator interface |
+| `pkg/interfaces/store/` | Store interface with IdPkTs, EventRef |
+| `pkg/interfaces/typer/` | Type introspection interface |
+
+---
+
+*Generated: 2025-12-24*
+*Analysis based on ORLY codebase v0.36.14*

Dockerfile

@@ -0,0 +1,64 @@
+# Multi-stage Dockerfile for ORLY relay
+
+# Stage 1: Build stage
+# Use Debian-based Go image to match runtime stage (avoids musl/glibc linker mismatch)
+FROM golang:1.25-bookworm AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends git make && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /build
+
+# Copy go mod files
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the binary with CGO disabled
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o orly -ldflags="-w -s" .
+
+# Stage 2: Runtime stage
+# Use Debian slim instead of Alpine because Debian's libsecp256k1 includes
+# Schnorr signatures (secp256k1_schnorrsig_*) and ECDH which Nostr requires.
+# Alpine's libsecp256k1 is built without these modules.
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl libsecp256k1-1 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create app user
+RUN groupadd -g 1000 orly && \
+    useradd -m -u 1000 -g orly orly
+
+# Set working directory
+WORKDIR /app
+
+# Copy binary (libsecp256k1.so.1 is already installed via apt)
+COPY --from=builder /build/orly /app/orly
+
+# Create data directory
+RUN mkdir -p /data && chown -R orly:orly /data /app
+
+# Switch to app user
+USER orly
+
+# Expose ports
+EXPOSE 3334
+
+# Health check
+HEALTHCHECK --interval=10s --timeout=5s --start-period=20s --retries=3 \
+    CMD curl -f http://localhost:3334/ || exit 1
+
+# Set default environment variables
+ENV ORLY_LISTEN=0.0.0.0 \
+    ORLY_PORT=3334 \
+    ORLY_DATA_DIR=/data \
+    ORLY_LOG_LEVEL=info
+
+# Run the binary
+ENTRYPOINT ["/app/orly"]

Dockerfile.relay-tester

@@ -0,0 +1,43 @@
+# Dockerfile for relay-tester
+
+# Use Debian-based Go image to match runtime stage (avoids musl/glibc linker mismatch)
+FROM golang:1.25-bookworm AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /build
+
+# Copy go mod files
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the relay-tester binary
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o relay-tester ./cmd/relay-tester
+
+# Runtime stage
+# Use Debian slim instead of Alpine because Debian's libsecp256k1 includes
+# Schnorr signatures (secp256k1_schnorrsig_*) and ECDH which Nostr requires.
+# Alpine's libsecp256k1 is built without these modules.
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates libsecp256k1-1 && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy binary (libsecp256k1.so.1 is already installed via apt)
+COPY --from=builder /build/relay-tester /app/relay-tester
+
+# Default relay URL (can be overridden)
+ENV RELAY_URL=ws://orly:3334
+
+# Run the relay tester
+ENTRYPOINT ["/app/relay-tester"]
+CMD ["-url", "${RELAY_URL}"]

MESSAGE_QUEUE_FIX.md

@@ -1,119 +0,0 @@
-# Message Queue Fix
-
-## Issue Discovered
-
-When running the subscription test, the relay logs showed:
-```
-⚠️ ws->10.0.0.2 message queue full, dropping message (capacity=100)
-```
-
-## Root Cause
-
-The `messageProcessor` goroutine was processing messages **synchronously**, one at a time:
-
-```go
-// BEFORE (blocking)
-func (l *Listener) messageProcessor() {
-    for {
-        case req := <-l.messageQueue:
-            l.HandleMessage(req.data, req.remote)  // BLOCKS until done
-    }
-}
-```
-
-**Problem:**
-- `HandleMessage` → `HandleReq` can take several seconds (database queries, event delivery)
-- While one message is being processed, new messages pile up in the queue
-- Queue fills up (100 message capacity)
-- New messages get dropped
-
-## Solution
-
-Process messages **concurrently** by launching each in its own goroutine (khatru pattern):
-
-```go
-// AFTER (concurrent)
-func (l *Listener) messageProcessor() {
-    for {
-        case req := <-l.messageQueue:
-            go l.HandleMessage(req.data, req.remote)  // NON-BLOCKING
-    }
-}
-```
-
-**Benefits:**
-- Multiple messages can be processed simultaneously
-- Fast operations (CLOSE, AUTH) don't wait behind slow operations (REQ)
-- Queue rarely fills up
-- No message drops
-
-## khatru Pattern
-
-This matches how khatru handles messages:
-
-1. **Sequential parsing** (in read loop) - Parser state can't be shared
-2. **Concurrent handling** (separate goroutines) - Each message independent
-
-From khatru:
-```go
-// Parse message (sequential, in read loop)
-envelope, err := smp.ParseMessage(message)
-
-// Handle message (concurrent, in goroutine)
-go func(message string) {
-    switch env := envelope.(type) {
-    case *nostr.EventEnvelope:
-        handleEvent(ctx, ws, env, rl)
-    case *nostr.ReqEnvelope:
-        handleReq(ctx, ws, env, rl)
-    // ...
-    }
-}(message)
-```
-
-## Files Changed
-
-- `app/listener.go:199` - Added `go` keyword before `l.HandleMessage()`
-
-## Impact
-
-**Before:**
-- Message queue filled up quickly
-- Messages dropped under load
-- Slow operations blocked everything
-
-**After:**
-- Messages processed concurrently
-- Queue rarely fills up
-- Each message type processed at its own pace
-
-## Testing
-
-```bash
-# Build with fix
-go build -o orly
-
-# Run relay
-./orly
-
-# Run subscription test (should not see queue warnings)
-./subscription-test-simple -duration 120
-```
-
-## Performance Notes
-
-**Goroutine overhead:** Minimal (~2KB per goroutine)
-- Modern Go runtime handles thousands of goroutines efficiently
-- Typical connection: 1-5 concurrent goroutines at a time
-- Under load: Goroutines naturally throttle based on CPU/IO capacity
-
-**Message ordering:** No longer guaranteed within a connection
-- This is fine for Nostr protocol (messages are independent)
-- Each message type can complete at its own pace
-- Matches khatru behavior
-
-## Summary
-
-The message queue was filling up because messages were processed synchronously. By processing them concurrently (one goroutine per message), we match khatru's proven architecture and eliminate message drops.
-
-**Status:** ✅ Fixed in app/listener.go:199

PUBLISHER_FIX.md

@@ -1,169 +0,0 @@
-# Critical Publisher Bug Fix
-
-## Issue Discovered
-
-Events were being published successfully but **never delivered to subscribers**. The test showed:
-- Publisher logs: "saved event"
-- Subscriber logs: No events received
-- No delivery timeouts or errors
-
-## Root Cause
-
-The `Subscription` struct in `app/publisher.go` was missing the `Receiver` field:
-
-```go
-// BEFORE - Missing Receiver field
-type Subscription struct {
-	remote       string
-	AuthedPubkey []byte
-	*filter.S
-}
-```
-
-This meant:
-1. Subscriptions were registered with receiver channels in `handle-req.go`
-2. Publisher stored subscriptions but **NEVER stored the receiver channels**
-3. Consumer goroutines waited on receiver channels
-4. Publisher's `Deliver()` tried to send directly to write channels (bypassing consumers)
-5. Events never reached the consumer goroutines → never delivered to clients
-
-## The Architecture (How it Should Work)
-
-```
-Event Published
-    ↓
-Publisher.Deliver() matches filters
-    ↓
-Sends event to Subscription.Receiver channel ← THIS WAS MISSING
-    ↓
-Consumer goroutine reads from Receiver
-    ↓
-Formats as EVENT envelope
-    ↓
-Sends to write channel
-    ↓
-Write worker sends to client
-```
-
-## The Fix
-
-### 1. Add Receiver Field to Subscription Struct
-
-**File**: `app/publisher.go:29-34`
-
-```go
-// AFTER - With Receiver field
-type Subscription struct {
-	remote       string
-	AuthedPubkey []byte
-	Receiver     event.C // Channel for delivering events to this subscription
-	*filter.S
-}
-```
-
-### 2. Store Receiver When Registering Subscription
-
-**File**: `app/publisher.go:125,130`
-
-```go
-// BEFORE
-subs[m.Id] = Subscription{
-	S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey,
-}
-
-// AFTER
-subs[m.Id] = Subscription{
-	S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey, Receiver: m.Receiver,
-}
-```
-
-### 3. Send Events to Receiver Channel (Not Write Channel)
-
-**File**: `app/publisher.go:242-266`
-
-```go
-// BEFORE - Tried to format and send directly to write channel
-var res *eventenvelope.Result
-if res, err = eventenvelope.NewResultWith(d.id, ev); chk.E(err) {
-	// ...
-}
-msgData := res.Marshal(nil)
-writeChan <- publish.WriteRequest{Data: msgData, MsgType: websocket.TextMessage}
-
-// AFTER - Send raw event to receiver channel
-if d.sub.Receiver == nil {
-	log.E.F("subscription %s has nil receiver channel", d.id)
-	continue
-}
-
-select {
-case d.sub.Receiver <- ev:
-	log.D.F("subscription delivery QUEUED: event=%s to=%s sub=%s",
-		hex.Enc(ev.ID), d.sub.remote, d.id)
-case <-time.After(DefaultWriteTimeout):
-	log.E.F("subscription delivery TIMEOUT: event=%s to=%s sub=%s",
-		hex.Enc(ev.ID), d.sub.remote, d.id)
-}
-```
-
-## Why This Pattern Matters (khatru Architecture)
-
-The khatru pattern uses **per-subscription consumer goroutines** for good reasons:
-
-1. **Separation of Concerns**: Publisher just matches filters and sends to channels
-2. **Formatting Isolation**: Each consumer formats events for its specific subscription
-3. **Backpressure Handling**: Channel buffers naturally throttle fast publishers
-4. **Clean Cancellation**: Context cancels consumer goroutine, channel cleanup is automatic
-5. **No Lock Contention**: Publisher doesn't hold locks during I/O operations
-
-## Files Modified
-
-| File | Lines | Change |
-|------|-------|--------|
-| `app/publisher.go` | 32 | Add `Receiver event.C` field to Subscription |
-| `app/publisher.go` | 125, 130 | Store Receiver when registering |
-| `app/publisher.go` | 242-266 | Send to receiver channel instead of write channel |
-| `app/publisher.go` | 3-19 | Remove unused imports (chk, eventenvelope) |
-
-## Testing
-
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Subscribe
-websocat ws://localhost:3334 <<< '["REQ","test",{"kinds":[1]}]'
-
-# Terminal 3: Publish event
-websocat ws://localhost:3334 <<< '["EVENT",{"kind":1,"content":"test",...}]'
-```
-
-**Expected**: Terminal 2 receives the event immediately
-
-## Impact
-
-**Before:**
-- ❌ No events delivered to subscribers
-- ❌ Publisher tried to bypass consumer goroutines
-- ❌ Consumer goroutines blocked forever waiting on receiver channels
-- ❌ Architecture didn't follow khatru pattern
-
-**After:**
-- ✅ Events delivered via receiver channels
-- ✅ Consumer goroutines receive and format events
-- ✅ Full khatru pattern implementation
-- ✅ Proper separation of concerns
-
-## Summary
-
-The subscription stability fixes in the previous work correctly implemented:
-- Per-subscription consumer goroutines ✅
-- Independent contexts ✅
-- Concurrent message processing ✅
-
-But the publisher was never connected to the consumer goroutines! This fix completes the implementation by:
-- Storing receiver channels in subscriptions ✅
-- Sending events to receiver channels ✅
-- Letting consumers handle formatting and delivery ✅
-
-**Result**: Events now flow correctly from publisher → receiver channel → consumer → client

QUICK_START.md

@@ -1,75 +0,0 @@
-# Quick Start - Subscription Stability Testing
-
-## TL;DR
-
-Subscriptions were dropping. Now they're fixed. Here's how to verify:
-
-## 1. Build Everything
-
-```bash
-go build -o orly
-go build -o subscription-test ./cmd/subscription-test
-```
-
-## 2. Test It
-
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run test
-./subscription-test -url ws://localhost:3334 -duration 60 -v
-```
-
-## 3. Expected Output
-
-```
-✓ Connected
-✓ Received EOSE - subscription is active
-
-Waiting for real-time events...
-
-[EVENT #1] id=abc123... kind=1 created=1234567890
-[EVENT #2] id=def456... kind=1 created=1234567891
-...
-
-[STATUS] Elapsed: 30s/60s | Events: 15 | Last event: 2s ago
-[STATUS] Elapsed: 60s/60s | Events: 30 | Last event: 1s ago
-
-✓ TEST PASSED - Subscription remained stable
-```
-
-## What Changed?
-
-**Before:** Subscriptions dropped after ~30-60 seconds
-**After:** Subscriptions stay active indefinitely
-
-## Key Files Modified
-
-- `app/listener.go` - Added subscription tracking
-- `app/handle-req.go` - Consumer goroutines per subscription
-- `app/handle-close.go` - Proper cleanup
-- `app/handle-websocket.go` - Cancel all subs on disconnect
-
-## Why Did It Break?
-
-Receiver channels were created but never consumed → filled up → publisher timeout → subscription removed
-
-## How Is It Fixed?
-
-Each subscription now has a goroutine that continuously reads from its channel and forwards events to the client (khatru pattern).
-
-## More Info
-
-- **Technical details:** [SUBSCRIPTION_STABILITY_FIXES.md](SUBSCRIPTION_STABILITY_FIXES.md)
-- **Full testing guide:** [TESTING_GUIDE.md](TESTING_GUIDE.md)
-- **Complete summary:** [SUMMARY.md](SUMMARY.md)
-
-## Questions?
-
-```bash
-./subscription-test -h     # Test tool help
-export ORLY_LOG_LEVEL=debug  # Enable debug logs
-```
-
-That's it! 🎉

README.md

@@ -0,0 +1,635 @@
+# next.orly.dev
+
+---
+
+![orly.dev](./docs/orly.png)
+
+![Version v0.24.1](https://img.shields.io/badge/version-v0.24.1-blue.svg)
+[![Documentation](https://img.shields.io/badge/godoc-documentation-blue.svg)](https://pkg.go.dev/next.orly.dev)
+[![Support this project](https://img.shields.io/badge/donate-geyser_crowdfunding_project_page-orange.svg)](https://geyser.fund/project/orly)
+
+zap me: <20>mlekudev@getalby.com
+
+follow me on [nostr](https://jumble.social/users/npub1fjqqy4a93z5zsjwsfxqhc2764kvykfdyttvldkkkdera8dr78vhsmmleku)
+
+## ⚠️ Bug Reports & Feature Requests
+
+**Bug reports and feature requests that do not follow the protocol will not be accepted.**
+
+Before submitting any issue, you must read and follow [BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md](./BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md).
+
+Requirements:
+- **Bug reports**: Include environment details, reproduction steps, expected/actual behavior, and logs
+- **Feature requests**: Include problem statement, proposed solution, and use cases
+- **Both**: Search existing issues first, verify with latest version, provide minimal reproduction
+
+Issues missing required information will be closed without review.
+
+## ⚠️ System Requirements
+
+> **IMPORTANT: ORLY requires a minimum of 500MB of free memory to operate.**
+>
+> The relay uses adaptive PID-controlled rate limiting to manage memory pressure. By default, it will:
+> - Auto-detect available system memory at startup
+> - Target 66% of available memory, capped at 1.5GB for optimal performance
+> - **Fail to start** if less than 500MB is available
+>
+> You can override the memory target with `ORLY_RATE_LIMIT_TARGET_MB` (e.g., `ORLY_RATE_LIMIT_TARGET_MB=2000` for 2GB).
+>
+> To disable rate limiting (not recommended): `ORLY_RATE_LIMIT_ENABLED=false`
+
+## About
+
+ORLY is a nostr relay written from the ground up to be performant, low latency, and built with a number of features designed to make it well suited for:
+
+- personal relays
+- small community relays
+- business deployments and RaaS (Relay as a Service) with a nostr-native NWC client to allow accepting payments through NWC capable lightning nodes
+- high availability clusters for reliability and/or providing a unified data set across multiple regions
+
+## Performance & Cryptography
+
+ORLY leverages high-performance libraries and custom optimizations for exceptional speed:
+
+- **SIMD Libraries**: Uses [minio/sha256-simd](https://github.com/minio/sha256-simd) for accelerated SHA256 hashing
+- **p256k1 Cryptography**: Implements [p256k1.mleku.dev](https://github.com/p256k1/p256k1) for fast elliptic curve operations optimized for nostr
+- **Fast Message Encoders**: High-performance encoding/decoding with [templexxx/xhex](https://github.com/templexxx/xhex) for SIMD-accelerated hex operations
+
+The encoders achieve **24% faster JSON marshaling**, **16% faster canonical encoding**, and **54-91% reduction in memory allocations** through custom buffer pre-allocation and zero-allocation optimization techniques.
+
+ORLY uses a fast embedded [badger](https://github.com/hypermodeinc/badger) database with a database designed for high performance querying and event storage.
+
+## Building
+
+ORLY is a standard Go application that can be built using the Go toolchain.
+
+### Prerequisites
+
+- Go 1.25.3 or later
+- Git
+- For web UI: [Bun](https://bun.sh/) JavaScript runtime
+
+### Basic Build
+
+To build the relay binary only:
+
+```bash
+git clone <repository-url>
+cd next.orly.dev
+go build -o orly
+```
+
+### Building with Web UI
+
+To build with the embedded web interface:
+
+```bash
+# Build the Svelte web application
+cd app/web
+bun install
+bun run build
+
+# Build the Go binary from project root
+cd ../../
+go build -o orly
+```
+
+The recommended way to build and embed the web UI is using the provided script:
+
+```bash
+./scripts/update-embedded-web.sh
+```
+
+This script will:
+- Build the Svelte app in `app/web` to `app/web/dist` using Bun (preferred) or fall back to npm/yarn/pnpm
+- Run `go install` from the repository root so the binary picks up the new embedded assets
+- Automatically detect and use the best available JavaScript package manager
+
+For manual builds, you can also use:
+
+```bash
+#!/bin/bash
+# build.sh
+echo "Building Svelte app..."
+cd app/web
+bun install
+bun run build
+
+echo "Building Go binary..."
+cd ../../
+go build -o orly
+
+echo "Build complete!"
+```
+
+Make it executable with `chmod +x build.sh` and run with `./build.sh`.
+
+## Core Features
+
+### Web UI
+
+ORLY includes a modern web-based user interface built with [Svelte](https://svelte.dev/) for relay management and monitoring.
+
+- **Secure Authentication**: Nostr key pair authentication with challenge-response
+- **Event Management**: Browse, export, import, and search events
+- **User Administration**: Role-based permissions (guest, user, admin, owner)
+- **Sprocket Management**: Upload and monitor event processing scripts
+- **Real-time Updates**: Live event streaming and system monitoring
+- **Responsive Design**: Works on desktop and mobile devices
+- **Dark/Light Themes**: Persistent theme preferences
+
+The web UI is embedded in the relay binary and accessible at the relay's root path.
+
+#### Web UI Development
+
+For development with hot-reloading, ORLY can proxy web requests to a local dev server while still handling WebSocket relay connections and API requests.
+
+**Environment Variables:**
+
+- `ORLY_WEB_DISABLE` - Set to `true` to disable serving the embedded web UI
+- `ORLY_WEB_DEV_PROXY_URL` - URL of the dev server to proxy web requests to (e.g., `localhost:8080`)
+
+**Setup:**
+
+1. Start the dev server (in one terminal):
+
+```bash
+cd app/web
+bun install
+bun run dev
+```
+
+Note the port sirv is listening on (e.g., `http://localhost:8080`).
+
+2. Start the relay with dev proxy enabled (in another terminal):
+
+```bash
+export ORLY_WEB_DISABLE=true
+export ORLY_WEB_DEV_PROXY_URL=localhost:8080
+./orly
+```
+
+The relay will:
+
+- Handle WebSocket connections at `/` for Nostr protocol
+- Handle API requests at `/api/*`
+- Proxy all other requests (HTML, JS, CSS, assets) to the dev server
+
+**With a reverse proxy/tunnel:**
+
+If you're running behind a reverse proxy or tunnel (e.g., Caddy, nginx, Cloudflare Tunnel), the setup is the same. The relay listens locally and your reverse proxy forwards traffic to it:
+
+```
+Browser <20> Reverse Proxy <20> ORLY (port 3334) <20> Dev Server (port 8080)
+                              <20>
+                         WebSocket/API
+```
+
+Example with the relay on port 3334 and sirv on port 8080:
+
+```bash
+# Terminal 1: Dev server
+cd app/web && bun run dev
+# Output: Your application is ready~!
+#         Local: http://localhost:8080
+
+# Terminal 2: Relay
+export ORLY_WEB_DISABLE=true
+export ORLY_WEB_DEV_PROXY_URL=localhost:8080
+export ORLY_PORT=3334
+./orly
+```
+
+**Disabling the web UI without a proxy:**
+
+If you only want to disable the embedded web UI (without proxying to a dev server), just set `ORLY_WEB_DISABLE=true` without setting `ORLY_WEB_DEV_PROXY_URL`. The relay will return 404 for web UI requests while still handling WebSocket and API requests.
+
+### Sprocket Event Processing
+
+ORLY includes a powerful sprocket system for external event processing scripts. Sprocket scripts enable custom filtering, validation, and processing logic for Nostr events before storage.
+
+- **Real-time Processing**: Scripts receive events via stdin and respond with JSONL decisions
+- **Three Actions**: `accept`, `reject`, or `shadowReject` events based on custom logic
+- **Automatic Recovery**: Failed scripts are automatically disabled with periodic recovery attempts
+- **Web UI Management**: Upload, configure, and monitor scripts through the admin interface
+
+```bash
+export ORLY_SPROCKET_ENABLED=true
+export ORLY_APP_NAME="ORLY"
+# Place script at ~/.config/ORLY/sprocket.sh
+```
+
+For detailed configuration and examples, see the [sprocket documentation](docs/sprocket/).
+
+### Policy System
+
+ORLY includes a comprehensive policy system for fine-grained control over event storage and retrieval. Configure custom validation rules, access controls, size limits, and age restrictions.
+
+- **Access Control**: Allow/deny based on pubkeys, roles, or social relationships
+- **Content Filtering**: Size limits, age validation, and custom rules
+- **Script Integration**: Execute custom scripts for complex policy logic
+- **Real-time Enforcement**: Policies applied to both read and write operations
+
+```bash
+export ORLY_POLICY_ENABLED=true
+# Default policy file: ~/.config/ORLY/policy.json
+
+# OPTIONAL: Use a custom policy file location
+# WARNING: ORLY_POLICY_PATH MUST be an ABSOLUTE path (starting with /)
+# Relative paths will be REJECTED and the relay will fail to start
+export ORLY_POLICY_PATH=/etc/orly/policy.json
+```
+
+For detailed configuration and examples, see the [Policy Usage Guide](docs/POLICY_USAGE_GUIDE.md).
+
+## Deployment
+
+ORLY includes an automated deployment script that handles Go installation, dependency setup, building, and systemd service configuration.
+
+### Automated Deployment
+
+The deployment script (`scripts/deploy.sh`) provides a complete setup solution:
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd next.orly.dev
+
+# Run the deployment script
+./scripts/deploy.sh
+```
+
+The script will:
+
+1. **Install Go 1.25.3** if not present (in `~/.local/go`)
+2. **Configure environment** by creating `~/.goenv` and updating `~/.bashrc`
+3. **Build the relay** with embedded web UI using `update-embedded-web.sh`
+4. **Set capabilities** for port 443 binding (requires sudo)
+5. **Install binary** to `~/.local/bin/orly`
+6. **Create systemd service** and enable it
+
+After deployment, reload your shell environment:
+
+```bash
+source ~/.bashrc
+```
+
+### TLS Configuration
+
+ORLY supports automatic TLS certificate management with Let's Encrypt and custom certificates:
+
+```bash
+# Enable TLS with Let's Encrypt for specific domains
+export ORLY_TLS_DOMAINS=relay.example.com,backup.relay.example.com
+
+# Optional: Use custom certificates (will load .pem and .key files)
+export ORLY_CERTS=/path/to/cert1,/path/to/cert2
+
+# When TLS domains are configured, ORLY will:
+# - Listen on port 443 for HTTPS/WSS
+# - Listen on port 80 for ACME challenges
+# - Ignore ORLY_PORT setting
+```
+
+Certificate files should be named with `.pem` and `.key` extensions:
+- `/path/to/cert1.pem` (certificate)
+- `/path/to/cert1.key` (private key)
+
+### systemd Service Management
+
+The deployment script creates a systemd service for easy management:
+
+```bash
+# Start the service
+sudo systemctl start orly
+
+# Stop the service
+sudo systemctl stop orly
+
+# Restart the service
+sudo systemctl restart orly
+
+# Enable service to start on boot
+sudo systemctl enable orly --now
+
+# Disable service from starting on boot
+sudo systemctl disable orly --now
+
+# Check service status
+sudo systemctl status orly
+
+# View service logs
+sudo journalctl -u orly -f
+
+# View recent logs
+sudo journalctl -u orly --since "1 hour ago"
+```
+
+### Remote Deployment
+
+You can deploy ORLY on a remote server using SSH:
+
+```bash
+# Deploy to a VPS with SSH key authentication
+ssh user@your-server.com << 'EOF'
+  # Clone and deploy
+  git clone <repository-url>
+  cd next.orly.dev
+  ./scripts/deploy.sh
+
+  # Configure your relay
+  echo 'export ORLY_TLS_DOMAINS=relay.example.com' >> ~/.bashrc
+  echo 'export ORLY_ADMINS=npub1your_admin_key_here' >> ~/.bashrc
+
+  # Start the service
+  sudo systemctl start orly --now
+EOF
+
+# Check deployment status
+ssh user@your-server.com 'sudo systemctl status orly'
+```
+
+### Configuration
+
+After deployment, configure your relay by setting environment variables in your shell profile:
+
+```bash
+# Add to ~/.bashrc or ~/.profile
+export ORLY_TLS_DOMAINS=relay.example.com
+export ORLY_ADMINS=npub1your_admin_key
+export ORLY_ACL_MODE=follows
+export ORLY_APP_NAME="MyRelay"
+```
+
+Then restart the service:
+
+```bash
+source ~/.bashrc
+sudo systemctl restart orly
+```
+
+### Firewall Configuration
+
+Ensure your firewall allows the necessary ports:
+
+```bash
+# For TLS-enabled relays
+sudo ufw allow 80/tcp   # HTTP (ACME challenges)
+sudo ufw allow 443/tcp  # HTTPS/WSS
+
+# For non-TLS relays
+sudo ufw allow 3334/tcp # Default ORLY port
+
+# Enable firewall if not already enabled
+sudo ufw enable
+```
+
+### Monitoring
+
+Monitor your relay using systemd and standard Linux tools:
+
+```bash
+# Service status and logs
+sudo systemctl status orly
+sudo journalctl -u orly -f
+
+# Resource usage
+htop
+sudo ss -tulpn | grep orly
+
+# Disk usage (database grows over time)
+du -sh ~/.local/share/ORLY/
+
+# Check TLS certificates (if using Let's Encrypt)
+ls -la ~/.local/share/ORLY/autocert/
+```
+
+## Testing
+
+ORLY includes comprehensive testing tools for protocol validation and performance testing.
+
+- **Protocol Testing**: Use `relay-tester` for Nostr protocol compliance validation
+- **Stress Testing**: Performance testing under various load conditions
+- **Benchmark Suite**: Comparative performance testing across relay implementations
+
+For detailed testing instructions, multi-relay testing scenarios, and advanced usage, see the [Relay Testing Guide](docs/RELAY_TESTING_GUIDE.md).
+
+The benchmark suite provides comprehensive performance testing and comparison across multiple relay implementations, including throughput, latency, and memory usage metrics.
+
+## Command-Line Tools
+
+ORLY includes several command-line utilities in the `cmd/` directory for testing, debugging, and administration.
+
+### relay-tester
+
+Nostr protocol compliance testing tool. Validates that a relay correctly implements the Nostr protocol specification.
+
+```bash
+# Run all protocol compliance tests
+go run ./cmd/relay-tester -url ws://localhost:3334
+
+# List available tests
+go run ./cmd/relay-tester -list
+
+# Run specific test
+go run ./cmd/relay-tester -url ws://localhost:3334 -test "Basic Event"
+
+# Output results as JSON
+go run ./cmd/relay-tester -url ws://localhost:3334 -json
+```
+
+### benchmark
+
+Comprehensive relay performance benchmarking tool. Tests event storage, queries, and subscription performance with detailed latency metrics (P90, P95, P99).
+
+```bash
+# Run benchmarks against local database
+go run ./cmd/benchmark -data-dir /tmp/bench-db -events 10000 -workers 4
+
+# Run benchmarks against a running relay
+go run ./cmd/benchmark -relay ws://localhost:3334 -events 5000
+
+# Use different database backends
+go run ./cmd/benchmark -dgraph -events 10000
+go run ./cmd/benchmark -neo4j -events 10000
+```
+
+The `cmd/benchmark/` directory also includes Docker Compose configurations for comparative benchmarks across multiple relay implementations (strfry, nostr-rs-relay, khatru, etc.).
+
+### stresstest
+
+Load testing tool for evaluating relay performance under sustained high-traffic conditions. Generates events with random content and tags to simulate realistic workloads.
+
+```bash
+# Run stress test with 10 concurrent workers
+go run ./cmd/stresstest -url ws://localhost:3334 -workers 10 -duration 60s
+
+# Generate events with random p-tags (up to 100 per event)
+go run ./cmd/stresstest -url ws://localhost:3334 -workers 5
+```
+
+### blossomtest
+
+Tests the Blossom blob storage protocol (BUD-01/BUD-02) implementation. Validates upload, download, and authentication flows.
+
+```bash
+# Test with generated key
+go run ./cmd/blossomtest -url http://localhost:3334 -size 1024
+
+# Test with specific nsec
+go run ./cmd/blossomtest -url http://localhost:3334 -nsec nsec1...
+
+# Test anonymous uploads (no authentication)
+go run ./cmd/blossomtest -url http://localhost:3334 -no-auth
+```
+
+### aggregator
+
+Event aggregation utility that fetches events from multiple relays using bloom filters for deduplication. Useful for syncing events across relays with memory-efficient duplicate detection.
+
+```bash
+go run ./cmd/aggregator -relays wss://relay1.com,wss://relay2.com -output events.jsonl
+```
+
+### convert
+
+Key format conversion utility. Converts between hex and bech32 (npub/nsec) formats for Nostr keys.
+
+```bash
+# Convert npub to hex
+go run ./cmd/convert npub1abc...
+
+# Convert hex to npub
+go run ./cmd/convert 0123456789abcdef...
+
+# Convert secret key (nsec or hex) - outputs both nsec and derived npub
+go run ./cmd/convert --secret nsec1xyz...
+```
+
+### FIND
+
+Free Internet Name Daemon - CLI tool for the distributed naming system. Manages name registration, transfers, and certificate issuance.
+
+```bash
+# Validate a name format
+go run ./cmd/FIND verify-name example.nostr
+
+# Generate a new key pair
+go run ./cmd/FIND generate-key
+
+# Create a registration proposal
+go run ./cmd/FIND register myname.nostr
+
+# Transfer a name to a new owner
+go run ./cmd/FIND transfer myname.nostr npub1newowner...
+```
+
+### policytest
+
+Tests the policy system for event write control. Validates that policy rules correctly allow or reject events based on kind, pubkey, and other criteria.
+
+```bash
+go run ./cmd/policytest -url ws://localhost:3334 -type event -kind 4678
+go run ./cmd/policytest -url ws://localhost:3334 -type req -kind 1
+go run ./cmd/policytest -url ws://localhost:3334 -type publish-and-query -count 5
+```
+
+### policyfiltertest
+
+Tests policy-based filtering with authorized and unauthorized pubkeys. Validates access control rules for specific users.
+
+```bash
+go run ./cmd/policyfiltertest -url ws://localhost:3334 \
+  -allowed-pubkey <hex> -allowed-sec <hex> \
+  -unauthorized-pubkey <hex> -unauthorized-sec <hex>
+```
+
+### subscription-test
+
+Tests WebSocket subscription stability over extended periods. Monitors for dropped subscriptions and connection issues.
+
+```bash
+# Run subscription stability test for 60 seconds
+go run ./cmd/subscription-test -url ws://localhost:3334 -duration 60 -kind 1
+
+# With verbose output
+go run ./cmd/subscription-test -url ws://localhost:3334 -duration 120 -v
+```
+
+### subscription-test-simple
+
+Simplified subscription stability test that verifies subscriptions remain active without dropping over the test duration.
+
+```bash
+go run ./cmd/subscription-test-simple -url ws://localhost:3334 -duration 120
+```
+
+## Access Control
+
+### Follows ACL
+
+The follows ACL (Access Control List) system provides flexible relay access control based on social relationships in the Nostr network.
+
+```bash
+export ORLY_ACL_MODE=follows
+export ORLY_ADMINS=npub1fjqqy4a93z5zsjwsfxqhc2764kvykfdyttvldkkkdera8dr78vhsmmleku
+./orly
+```
+
+The system grants write access to users followed by designated admins, with read-only access for others. Follow lists update dynamically as admins modify their relationships.
+
+### Cluster Replication
+
+ORLY supports distributed relay clusters using active replication. When configured with peer relays, ORLY will automatically synchronize events between cluster members using efficient HTTP polling.
+
+```bash
+export ORLY_RELAY_PEERS=https://peer1.example.com,https://peer2.example.com
+export ORLY_CLUSTER_ADMINS=npub1cluster_admin_key
+```
+
+**Privacy Considerations:** By default, ORLY propagates all events including privileged events (DMs, gift wraps, etc.) to cluster peers for complete synchronization. This ensures no data loss but may expose private communications to other relay operators in your cluster.
+
+To enhance privacy, you can disable propagation of privileged events:
+
+```bash
+export ORLY_CLUSTER_PROPAGATE_PRIVILEGED_EVENTS=false
+```
+
+**Important:** When disabled, privileged events will not be replicated to peer relays. This provides better privacy but means these events will only be available on the originating relay. Users should be aware that accessing their privileged events may require connecting directly to the relay where they were originally published.
+
+## Developer Notes
+
+### Binary-Optimized Tag Storage
+
+The nostr library (`git.mleku.dev/mleku/nostr/encoders/tag`) uses binary optimization for `e` and `p` tags to reduce memory usage and improve comparison performance.
+
+When events are unmarshaled from JSON, 64-character hex values in e/p tags are converted to 33-byte binary format (32 bytes hash + null terminator).
+
+**Important:** When working with e/p tag values in code:
+
+- **DO NOT** use `tag.Value()` directly - it returns raw bytes which may be binary, not hex
+- **ALWAYS** use `tag.ValueHex()` to get a hex string regardless of storage format
+- **Use** `tag.ValueBinary()` to get raw 32-byte binary (returns nil if not binary-encoded)
+
+```go
+// CORRECT: Use ValueHex() for hex decoding
+pt, err := hex.Dec(string(pTag.ValueHex()))
+
+// WRONG: Value() may return binary bytes, not hex
+pt, err := hex.Dec(string(pTag.Value()))  // Will fail for binary-encoded tags!
+```
+
+### Release Process
+
+The `/release` command pushes to multiple git remotes. To push to git.mleku.dev with the dedicated SSH key, ensure the `gitmlekudev` key is configured:
+
+```bash
+# SSH key should be at ~/.ssh/gitmlekudev
+# The release command uses GIT_SSH_COMMAND to specify this key:
+GIT_SSH_COMMAND="ssh -i ~/.ssh/gitmlekudev" git push ssh://mleku@git.mleku.dev:2222/mleku/next.orly.dev.git main --tags
+```
+
+Remotes pushed during release:
+- `origin` - Primary remote
+- `gitea` - Gitea mirror
+- `git.mleku.dev` - Using `gitmlekudev` SSH key

SUBSCRIPTION_STABILITY_FIXES.md

@@ -1,371 +0,0 @@
-# WebSocket Subscription Stability Fixes
-
-## Executive Summary
-
-This document describes critical fixes applied to resolve subscription drop issues in the ORLY Nostr relay. The primary issue was **receiver channels were created but never consumed**, causing subscriptions to appear "dead" after a short period.
-
-## Root Causes Identified
-
-### 1. **Missing Receiver Channel Consumer** (Critical)
-**Location:** [app/handle-req.go:616](app/handle-req.go#L616)
-
-**Problem:**
-- `HandleReq` created a receiver channel: `receiver := make(event.C, 32)`
-- This channel was passed to the publisher but **never consumed**
-- When events were published, the channel filled up (32-event buffer)
-- Publisher attempts to send timed out after 3 seconds
-- Publisher assumed connection was dead and removed subscription
-
-**Impact:** Subscriptions dropped after receiving ~32 events or after inactivity timeout.
-
-### 2. **No Independent Subscription Context**
-**Location:** [app/handle-req.go](app/handle-req.go)
-
-**Problem:**
-- Subscriptions used the listener's connection context directly
-- If the query context was cancelled (timeout, error), it affected active subscriptions
-- No way to independently cancel individual subscriptions
-- Similar to khatru, each subscription needs its own context hierarchy
-
-**Impact:** Query timeouts or errors could inadvertently cancel active subscriptions.
-
-### 3. **Incomplete Subscription Cleanup**
-**Location:** [app/handle-close.go](app/handle-close.go)
-
-**Problem:**
-- `HandleClose` sent cancel signal to publisher
-- But didn't close receiver channels or stop consumer goroutines
-- Led to goroutine leaks and channel leaks
-
-**Impact:** Memory leaks over time, especially with many short-lived subscriptions.
-
-## Solutions Implemented
-
-### 1. Per-Subscription Consumer Goroutines
-
-**Added in [app/handle-req.go:644-688](app/handle-req.go#L644-L688):**
-
-```go
-// Launch goroutine to consume from receiver channel and forward to client
-go func() {
-    defer func() {
-        // Clean up when subscription ends
-        l.subscriptionsMu.Lock()
-        delete(l.subscriptions, subID)
-        l.subscriptionsMu.Unlock()
-        log.D.F("subscription goroutine exiting for %s @ %s", subID, l.remote)
-    }()
-
-    for {
-        select {
-        case <-subCtx.Done():
-            // Subscription cancelled (CLOSE message or connection closing)
-            return
-        case ev, ok := <-receiver:
-            if !ok {
-                // Channel closed - subscription ended
-                return
-            }
-
-            // Forward event to client via write channel
-            var res *eventenvelope.Result
-            var err error
-            if res, err = eventenvelope.NewResultWith(subID, ev); chk.E(err) {
-                continue
-            }
-
-            // Write to client - this goes through the write worker
-            if err = res.Write(l); err != nil {
-                if !strings.Contains(err.Error(), "context canceled") {
-                    log.E.F("failed to write event to subscription %s @ %s: %v", subID, l.remote, err)
-                }
-                continue
-            }
-
-            log.D.F("delivered real-time event %s to subscription %s @ %s",
-                hexenc.Enc(ev.ID), subID, l.remote)
-        }
-    }
-}()
-```
-
-**Benefits:**
-- Events are continuously consumed from receiver channel
-- Channel never fills up
-- Publisher can always send without timeout
-- Clean shutdown when subscription is cancelled
-
-### 2. Independent Subscription Contexts
-
-**Added in [app/handle-req.go:621-627](app/handle-req.go#L621-L627):**
-
-```go
-// Create a dedicated context for this subscription that's independent of query context
-// but is child of the listener context so it gets cancelled when connection closes
-subCtx, subCancel := context.WithCancel(l.ctx)
-
-// Track this subscription so we can cancel it on CLOSE or connection close
-subID := string(env.Subscription)
-l.subscriptionsMu.Lock()
-l.subscriptions[subID] = subCancel
-l.subscriptionsMu.Unlock()
-```
-
-**Added subscription tracking to Listener struct [app/listener.go:46-47](app/listener.go#L46-L47):**
-
-```go
-// Subscription tracking for cleanup
-subscriptions    map[string]context.CancelFunc // Map of subscription ID to cancel function
-subscriptionsMu  sync.Mutex                     // Protects subscriptions map
-```
-
-**Benefits:**
-- Each subscription has independent lifecycle
-- Query timeouts don't affect active subscriptions
-- Clean cancellation via context pattern
-- Follows khatru's proven architecture
-
-### 3. Proper Subscription Cleanup
-
-**Updated [app/handle-close.go:29-48](app/handle-close.go#L29-L48):**
-
-```go
-subID := string(env.ID)
-
-// Cancel the subscription goroutine by calling its cancel function
-l.subscriptionsMu.Lock()
-if cancelFunc, exists := l.subscriptions[subID]; exists {
-    log.D.F("cancelling subscription %s for %s", subID, l.remote)
-    cancelFunc()
-    delete(l.subscriptions, subID)
-} else {
-    log.D.F("subscription %s not found for %s (already closed?)", subID, l.remote)
-}
-l.subscriptionsMu.Unlock()
-
-// Also remove from publisher's tracking
-l.publishers.Receive(
-    &W{
-        Cancel: true,
-        remote: l.remote,
-        Conn:   l.conn,
-        Id:     subID,
-    },
-)
-```
-
-**Updated connection cleanup in [app/handle-websocket.go:136-143](app/handle-websocket.go#L136-L143):**
-
-```go
-// Cancel all active subscriptions first
-listener.subscriptionsMu.Lock()
-for subID, cancelFunc := range listener.subscriptions {
-    log.D.F("cancelling subscription %s for %s", subID, remote)
-    cancelFunc()
-}
-listener.subscriptions = nil
-listener.subscriptionsMu.Unlock()
-```
-
-**Benefits:**
-- Subscriptions properly cancelled on CLOSE message
-- All subscriptions cancelled when connection closes
-- No goroutine or channel leaks
-- Clean resource management
-
-## Architecture Comparison: ORLY vs khatru
-
-### Before (Broken)
-```
-REQ → Create receiver channel → Register with publisher → Done
-                                        ↓
-Events published → Try to send to receiver → TIMEOUT (channel full)
-                                                  ↓
-                                          Remove subscription
-```
-
-### After (Fixed, khatru-style)
-```
-REQ → Create receiver channel → Register with publisher → Launch consumer goroutine
-                                        ↓                          ↓
-Events published → Send to receiver ──────────────→ Consumer reads → Forward to client
-                   (never blocks)                   (continuous)
-```
-
-### Key khatru Patterns Adopted
-
-1. **Dual-context architecture:**
-   - Connection context (`l.ctx`) - cancelled when connection closes
-   - Per-subscription context (`subCtx`) - cancelled on CLOSE or connection close
-
-2. **Consumer goroutine per subscription:**
-   - Dedicated goroutine reads from receiver channel
-   - Forwards events to write channel
-   - Clean shutdown via context cancellation
-
-3. **Subscription tracking:**
-   - Map of subscription ID → cancel function
-   - Enables targeted cancellation
-   - Clean bulk cancellation on disconnect
-
-4. **Write serialization:**
-   - Already implemented correctly with write worker
-   - Single goroutine handles all writes
-   - Prevents concurrent write panics
-
-## Testing
-
-### Manual Testing Recommendations
-
-1. **Long-running subscription test:**
-   ```bash
-   # Terminal 1: Start relay
-   ./orly
-
-   # Terminal 2: Connect and subscribe
-   websocat ws://localhost:3334
-   ["REQ","test",{"kinds":[1]}]
-
-   # Terminal 3: Publish events periodically
-   for i in {1..100}; do
-     # Publish event via your preferred method
-     sleep 10
-   done
-   ```
-
-   **Expected:** All 100 events should be received by the subscriber.
-
-2. **Multiple subscriptions test:**
-   ```bash
-   # Connect once, create multiple subscriptions
-   ["REQ","sub1",{"kinds":[1]}]
-   ["REQ","sub2",{"kinds":[3]}]
-   ["REQ","sub3",{"kinds":[7]}]
-
-   # Publish events of different kinds
-   # Verify each subscription receives only its kind
-   ```
-
-3. **Subscription closure test:**
-   ```bash
-   ["REQ","test",{"kinds":[1]}]
-   # Wait for EOSE
-   ["CLOSE","test"]
-
-   # Publish more kind 1 events
-   # Verify no events are received after CLOSE
-   ```
-
-### Automated Tests
-
-See [app/subscription_stability_test.go](app/subscription_stability_test.go) for comprehensive test suite:
-- `TestLongRunningSubscriptionStability` - 30-second subscription with events published every second
-- `TestMultipleConcurrentSubscriptions` - Multiple subscriptions on same connection
-
-## Performance Implications
-
-### Resource Usage
-
-**Before:**
-- Memory leak: ~100 bytes per abandoned subscription goroutine
-- Channel leak: ~32 events × ~5KB each = ~160KB per subscription
-- CPU: Wasted cycles on timeout retries in publisher
-
-**After:**
-- Clean goroutine shutdown: 0 leaks
-- Channels properly closed: 0 leaks
-- CPU: No wasted timeout retries
-
-### Scalability
-
-**Before:**
-- Max ~32 events per subscription before issues
-- Frequent subscription churn as they drop and reconnect
-- Publisher timeout overhead on every event broadcast
-
-**After:**
-- Unlimited events per subscription
-- Stable long-running subscriptions (hours/days)
-- Fast event delivery (no timeouts)
-
-## Monitoring Recommendations
-
-Add metrics to track subscription health:
-
-```go
-// In Server struct
-type SubscriptionMetrics struct {
-    ActiveSubscriptions  atomic.Int64
-    TotalSubscriptions   atomic.Int64
-    SubscriptionDrops    atomic.Int64
-    EventsDelivered      atomic.Int64
-    DeliveryTimeouts     atomic.Int64
-}
-```
-
-Log these metrics periodically to detect regressions.
-
-## Migration Notes
-
-### Compatibility
-
-These changes are **100% backward compatible**:
-- Wire protocol unchanged
-- Client behavior unchanged
-- Database schema unchanged
-- Configuration unchanged
-
-### Deployment
-
-1. Build with Go 1.21+
-2. Deploy as normal (no special steps)
-3. Restart relay
-4. Existing connections will be dropped (as expected with restart)
-5. New connections will use fixed subscription handling
-
-### Rollback
-
-If issues arise, revert commits:
-```bash
-git revert <commit-hash>
-go build -o orly
-```
-
-Old behavior will be restored.
-
-## Related Issues
-
-This fix resolves several related symptoms:
-- Subscriptions dropping after ~1 minute
-- Subscriptions receiving only first N events then stopping
-- Publisher timing out when broadcasting events
-- Goroutine leaks growing over time
-- Memory usage growing with subscription count
-
-## References
-
-- **khatru relay:** https://github.com/fiatjaf/khatru
-- **RFC 6455 WebSocket Protocol:** https://tools.ietf.org/html/rfc6455
-- **NIP-01 Basic Protocol:** https://github.com/nostr-protocol/nips/blob/master/01.md
-- **WebSocket skill documentation:** [.claude/skills/nostr-websocket](.claude/skills/nostr-websocket)
-
-## Code Locations
-
-All changes are in these files:
-- [app/listener.go](app/listener.go) - Added subscription tracking fields
-- [app/handle-websocket.go](app/handle-websocket.go) - Initialize fields, cancel all on close
-- [app/handle-req.go](app/handle-req.go) - Launch consumer goroutines, track subscriptions
-- [app/handle-close.go](app/handle-close.go) - Cancel specific subscriptions
-- [app/subscription_stability_test.go](app/subscription_stability_test.go) - Test suite (new file)
-
-## Conclusion
-
-The subscription stability issues were caused by a fundamental architectural flaw: **receiver channels without consumers**. By adopting khatru's proven pattern of per-subscription consumer goroutines with independent contexts, we've achieved:
-
-✅ Unlimited subscription lifetime
-✅ No event delivery timeouts
-✅ No resource leaks
-✅ Clean subscription lifecycle
-✅ Backward compatible
-
-The relay should now handle long-running subscriptions as reliably as khatru does in production.

SUMMARY.md

@@ -1,229 +0,0 @@
-# Subscription Stability Refactoring - Summary
-
-## Overview
-
-Successfully refactored WebSocket and subscription handling following khatru patterns to fix critical stability issues that caused subscriptions to drop after a short period.
-
-## Problem Identified
-
-**Root Cause:** Receiver channels were created but never consumed, causing:
-- Channels to fill up after 32 events (buffer limit)
-- Publisher timeouts when trying to send to full channels
-- Subscriptions being removed as "dead" connections
-- Events not delivered to active subscriptions
-
-## Solution Implemented
-
-Adopted khatru's proven architecture:
-
-1. **Per-subscription consumer goroutines** - Each subscription has a dedicated goroutine that continuously reads from its receiver channel and forwards events to the client
-
-2. **Independent subscription contexts** - Each subscription has its own cancellable context, preventing query timeouts from affecting active subscriptions
-
-3. **Proper lifecycle management** - Clean cancellation and cleanup on CLOSE messages and connection termination
-
-4. **Subscription tracking** - Map of subscription ID to cancel function for targeted cleanup
-
-## Files Changed
-
-- **[app/listener.go](app/listener.go)** - Added subscription tracking fields
-- **[app/handle-websocket.go](app/handle-websocket.go)** - Initialize subscription map, cancel all on close
-- **[app/handle-req.go](app/handle-req.go)** - Launch consumer goroutines for each subscription
-- **[app/handle-close.go](app/handle-close.go)** - Cancel specific subscriptions properly
-
-## New Tools Created
-
-### 1. Subscription Test Tool
-**Location:** `cmd/subscription-test/main.go`
-
-Native Go WebSocket client for testing subscription stability (no external dependencies like websocat).
-
-**Usage:**
-```bash
-./subscription-test -url ws://localhost:3334 -duration 60 -kind 1
-```
-
-**Features:**
-- Connects to relay and subscribes to events
-- Monitors for subscription drops
-- Reports event delivery statistics
-- No glibc dependencies (pure Go)
-
-### 2. Test Scripts
-**Location:** `scripts/test-subscriptions.sh`
-
-Convenience wrapper for running subscription tests.
-
-### 3. Documentation
-- **[SUBSCRIPTION_STABILITY_FIXES.md](SUBSCRIPTION_STABILITY_FIXES.md)** - Detailed technical explanation
-- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Comprehensive testing procedures
-- **[app/subscription_stability_test.go](app/subscription_stability_test.go)** - Go test suite (framework ready)
-
-## How to Test
-
-### Quick Test
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run subscription test
-./subscription-test -url ws://localhost:3334 -duration 60 -v
-
-# Terminal 3: Publish events (your method)
-# The subscription test will show events being received
-```
-
-### What Success Looks Like
-- ✅ Subscription receives EOSE immediately
-- ✅ Events delivered throughout entire test duration
-- ✅ No timeout errors in relay logs
-- ✅ Clean shutdown on Ctrl+C
-
-### What Failure Looked Like (Before Fix)
-- ❌ Events stop after ~32 events or ~30 seconds
-- ❌ "subscription delivery TIMEOUT" in logs
-- ❌ Subscriptions removed as "dead"
-
-## Architecture Comparison
-
-### Before (Broken)
-```
-REQ → Create channel → Register → Wait for events
-                                       ↓
-                            Events published → Try to send → TIMEOUT
-                                                                ↓
-                                                        Subscription removed
-```
-
-### After (Fixed - khatru style)
-```
-REQ → Create channel → Register → Launch consumer goroutine
-                                          ↓
-                            Events published → Send to channel
-                                                    ↓
-                                          Consumer reads → Forward to client
-                                          (continuous)
-```
-
-## Key Improvements
-
-| Aspect | Before | After |
-|--------|--------|-------|
-| Subscription lifetime | ~30-60 seconds | Unlimited (hours/days) |
-| Events per subscription | ~32 max | Unlimited |
-| Event delivery | Timeouts common | Always successful |
-| Resource leaks | Yes (goroutines, channels) | No leaks |
-| Multiple subscriptions | Interfered with each other | Independent |
-
-## Build Status
-
-✅ **All code compiles successfully**
-```bash
-go build -o orly                          # 26M binary
-go build -o subscription-test ./cmd/subscription-test  # 7.8M binary
-```
-
-## Performance Impact
-
-### Memory
-- **Per subscription:** ~10KB (goroutine stack + channel buffers)
-- **No leaks:** Goroutines and channels cleaned up properly
-
-### CPU
-- **Minimal:** Event-driven architecture, only active when events arrive
-- **No polling:** Uses select/channels for efficiency
-
-### Scalability
-- **Before:** Limited to ~1000 subscriptions due to leaks
-- **After:** Supports 10,000+ concurrent subscriptions
-
-## Backwards Compatibility
-
-✅ **100% Backward Compatible**
-- No wire protocol changes
-- No client changes required
-- No configuration changes needed
-- No database migrations required
-
-Existing clients will automatically benefit from improved stability.
-
-## Deployment
-
-1. **Build:**
-   ```bash
-   go build -o orly
-   ```
-
-2. **Deploy:**
-   Replace existing binary with new one
-
-3. **Restart:**
-   Restart relay service (existing connections will be dropped, new connections will use fixed code)
-
-4. **Verify:**
-   Run subscription-test tool to confirm stability
-
-5. **Monitor:**
-   Watch logs for "subscription delivery TIMEOUT" errors (should see none)
-
-## Monitoring
-
-### Key Metrics to Track
-
-**Positive indicators:**
-- "subscription X created and goroutine launched"
-- "delivered real-time event X to subscription Y"
-- "subscription delivery QUEUED"
-
-**Negative indicators (should not see):**
-- "subscription delivery TIMEOUT"
-- "removing failed subscriber connection"
-- "subscription goroutine exiting" (except on explicit CLOSE)
-
-### Log Levels
-
-```bash
-# For testing
-export ORLY_LOG_LEVEL=debug
-
-# For production
-export ORLY_LOG_LEVEL=info
-```
-
-## Credits
-
-**Inspiration:** khatru relay by fiatjaf
-- GitHub: https://github.com/fiatjaf/khatru
-- Used as reference for WebSocket patterns
-- Proven architecture in production
-
-**Pattern:** Per-subscription consumer goroutines with independent contexts
-
-## Next Steps
-
-1. ✅ Code implemented and building
-2. ⏳ **Run manual tests** (see TESTING_GUIDE.md)
-3. ⏳ Deploy to staging environment
-4. ⏳ Monitor for 24 hours
-5. ⏳ Deploy to production
-
-## Support
-
-For issues or questions:
-
-1. Check [TESTING_GUIDE.md](TESTING_GUIDE.md) for testing procedures
-2. Review [SUBSCRIPTION_STABILITY_FIXES.md](SUBSCRIPTION_STABILITY_FIXES.md) for technical details
-3. Enable debug logging: `export ORLY_LOG_LEVEL=debug`
-4. Run subscription-test with `-v` flag for verbose output
-
-## Conclusion
-
-The subscription stability issues have been resolved by adopting khatru's proven WebSocket patterns. The relay now properly manages subscription lifecycles with:
-
-- ✅ Per-subscription consumer goroutines
-- ✅ Independent contexts per subscription
-- ✅ Clean resource management
-- ✅ No event delivery timeouts
-- ✅ Unlimited subscription lifetime
-
-**The relay is now ready for production use with stable, long-running subscriptions.**

TESTING_GUIDE.md

@@ -1,300 +0,0 @@
-# Subscription Stability Testing Guide
-
-This guide explains how to test the subscription stability fixes.
-
-## Quick Test
-
-### 1. Start the Relay
-
-```bash
-# Build the relay with fixes
-go build -o orly
-
-# Start the relay
-./orly
-```
-
-### 2. Run the Subscription Test
-
-In another terminal:
-
-```bash
-# Run the built-in test tool
-./subscription-test -url ws://localhost:3334 -duration 60 -kind 1 -v
-
-# Or use the helper script
-./scripts/test-subscriptions.sh
-```
-
-### 3. Publish Events (While Test is Running)
-
-The subscription test will wait for events. You need to publish events while it's running to verify the subscription remains active.
-
-**Option A: Using the relay-tester tool (if available):**
-```bash
-go run cmd/relay-tester/main.go -url ws://localhost:3334
-```
-
-**Option B: Using your client application:**
-Publish events to the relay through your normal client workflow.
-
-**Option C: Manual WebSocket connection:**
-Use any WebSocket client to publish events:
-```json
-["EVENT",{"kind":1,"content":"Test event","created_at":1234567890,"tags":[],"pubkey":"...","id":"...","sig":"..."}]
-```
-
-## What to Look For
-
-### ✅ Success Indicators
-
-1. **Subscription stays active:**
-   - Test receives EOSE immediately
-   - Events are delivered throughout the entire test duration
-   - No "subscription may have dropped" warnings
-
-2. **Event delivery:**
-   - All published events are received by the subscription
-   - Events arrive within 1-2 seconds of publishing
-   - No delivery timeouts in relay logs
-
-3. **Clean shutdown:**
-   - Test can be interrupted with Ctrl+C
-   - Subscription closes cleanly
-   - No error messages in relay logs
-
-### ❌ Failure Indicators
-
-1. **Subscription drops:**
-   - Events stop being received after ~30-60 seconds
-   - Warning: "No events received for Xs"
-   - Relay logs show timeout errors
-
-2. **Event delivery failures:**
-   - Events are published but not received
-   - Relay logs show "delivery TIMEOUT" messages
-   - Subscription is removed from publisher
-
-3. **Resource leaks:**
-   - Memory usage grows over time
-   - Goroutine count increases continuously
-   - Connection not cleaned up properly
-
-## Test Scenarios
-
-### 1. Basic Long-Running Test
-
-**Duration:** 60 seconds
-**Event Rate:** 1 event every 2-5 seconds
-**Expected:** All events received, subscription stays active
-
-```bash
-./subscription-test -url ws://localhost:3334 -duration 60
-```
-
-### 2. Extended Duration Test
-
-**Duration:** 300 seconds (5 minutes)
-**Event Rate:** 1 event every 10 seconds
-**Expected:** All events received throughout 5 minutes
-
-```bash
-./subscription-test -url ws://localhost:3334 -duration 300
-```
-
-### 3. Multiple Subscriptions
-
-Run multiple test instances simultaneously:
-
-```bash
-# Terminal 1
-./subscription-test -url ws://localhost:3334 -duration 120 -kind 1 -sub sub1
-
-# Terminal 2
-./subscription-test -url ws://localhost:3334 -duration 120 -kind 1 -sub sub2
-
-# Terminal 3
-./subscription-test -url ws://localhost:3334 -duration 120 -kind 1 -sub sub3
-```
-
-**Expected:** All subscriptions receive events independently
-
-### 4. Idle Subscription Test
-
-**Duration:** 120 seconds
-**Event Rate:** Publish events only at start and end
-**Expected:** Subscription remains active even during long idle period
-
-```bash
-# Start test
-./subscription-test -url ws://localhost:3334 -duration 120
-
-# Publish 1-2 events immediately
-# Wait 100 seconds (subscription should stay alive)
-# Publish 1-2 more events
-# Verify test receives the late events
-```
-
-## Debugging
-
-### Enable Verbose Logging
-
-```bash
-# Relay
-export ORLY_LOG_LEVEL=debug
-./orly
-
-# Test tool
-./subscription-test -url ws://localhost:3334 -duration 60 -v
-```
-
-### Check Relay Logs
-
-Look for these log patterns:
-
-**Good (working subscription):**
-```
-subscription test-123456 created and goroutine launched for 127.0.0.1
-delivered real-time event abc123... to subscription test-123456 @ 127.0.0.1
-subscription delivery QUEUED: event=abc123... to=127.0.0.1
-```
-
-**Bad (subscription issues):**
-```
-subscription delivery TIMEOUT: event=abc123...
-removing failed subscriber connection
-subscription goroutine exiting unexpectedly
-```
-
-### Monitor Resource Usage
-
-```bash
-# Watch memory usage
-watch -n 1 'ps aux | grep orly'
-
-# Check goroutine count (requires pprof enabled)
-curl http://localhost:6060/debug/pprof/goroutine?debug=1
-```
-
-## Expected Performance
-
-With the fixes applied:
-
-- **Subscription lifetime:** Unlimited (hours/days)
-- **Event delivery latency:** < 100ms
-- **Max concurrent subscriptions:** Thousands per relay
-- **Memory per subscription:** ~10KB (goroutine + buffers)
-- **CPU overhead:** Minimal (event-driven)
-
-## Automated Tests
-
-Run the Go test suite:
-
-```bash
-# Run all tests
-./scripts/test.sh
-
-# Run subscription tests only (once implemented)
-go test -v -run TestLongRunningSubscription ./app
-go test -v -run TestMultipleConcurrentSubscriptions ./app
-```
-
-## Common Issues
-
-### Issue: "Failed to connect"
-
-**Cause:** Relay not running or wrong URL
-**Solution:**
-```bash
-# Check relay is running
-ps aux | grep orly
-
-# Verify port
-netstat -tlnp | grep 3334
-```
-
-### Issue: "No events received"
-
-**Cause:** No events being published
-**Solution:** Publish test events while test is running (see section 3 above)
-
-### Issue: "Subscription CLOSED by relay"
-
-**Cause:** Filter policy or ACL rejecting subscription
-**Solution:** Check relay configuration and ACL settings
-
-### Issue: Test hangs at EOSE
-
-**Cause:** Relay not sending EOSE
-**Solution:** Check relay logs for query errors
-
-## Manual Testing with Raw WebSocket
-
-If you prefer manual testing, you can use any WebSocket client:
-
-```bash
-# Install wscat (Node.js based, no glibc issues)
-npm install -g wscat
-
-# Connect and subscribe
-wscat -c ws://localhost:3334
-> ["REQ","manual-test",{"kinds":[1]}]
-
-# Wait for EOSE
-< ["EOSE","manual-test"]
-
-# Events should arrive as they're published
-< ["EVENT","manual-test",{"id":"...","kind":1,...}]
-```
-
-## Comparison: Before vs After Fixes
-
-### Before (Broken)
-
-```
-$ ./subscription-test -duration 60
-✓ Connected
-✓ Received EOSE
-[EVENT #1] id=abc123... kind=1
-[EVENT #2] id=def456... kind=1
-...
-[EVENT #30] id=xyz789... kind=1
-⚠ Warning: No events received for 35s - subscription may have dropped
-Test complete: 30 events received (expected 60)
-```
-
-### After (Fixed)
-
-```
-$ ./subscription-test -duration 60
-✓ Connected
-✓ Received EOSE
-[EVENT #1] id=abc123... kind=1
-[EVENT #2] id=def456... kind=1
-...
-[EVENT #60] id=xyz789... kind=1
-✓ TEST PASSED - Subscription remained stable
-Test complete: 60 events received
-```
-
-## Reporting Issues
-
-If subscriptions still drop after the fixes, please report with:
-
-1. Relay logs (with `ORLY_LOG_LEVEL=debug`)
-2. Test output
-3. Steps to reproduce
-4. Relay configuration
-5. Event publishing method
-
-## Summary
-
-The subscription stability fixes ensure:
-
-✅ Subscriptions remain active indefinitely
-✅ All events are delivered without timeouts
-✅ Clean resource management (no leaks)
-✅ Multiple concurrent subscriptions work correctly
-✅ Idle subscriptions don't timeout
-
-Follow the test scenarios above to verify these improvements in your deployment.

TEST_NOW.md

@@ -1,108 +0,0 @@
-# Test Subscription Stability NOW
-
-## Quick Test (No Events Required)
-
-This test verifies the subscription stays registered without needing to publish events:
-
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run simple test
-./subscription-test-simple -url ws://localhost:3334 -duration 120
-```
-
-**Expected output:**
-```
-✓ Connected
-✓ Received EOSE - subscription is active
-
-Subscription is active. Monitoring for 120 seconds...
-
-[  10s/120s] Messages: 1 | Last message: 5s ago | Status: ACTIVE (recent message)
-[  20s/120s] Messages: 1 | Last message: 15s ago | Status: IDLE (normal)
-[  30s/120s] Messages: 1 | Last message: 25s ago | Status: IDLE (normal)
-...
-[120s/120s] Messages: 1 | Last message: 115s ago | Status: QUIET (possibly normal)
-
-✓ TEST PASSED
-Subscription remained active throughout test period.
-```
-
-## Full Test (With Events)
-
-For comprehensive testing with event delivery:
-
-```bash
-# Terminal 1: Start relay
-./orly
-
-# Terminal 2: Run test
-./subscription-test -url ws://localhost:3334 -duration 60
-
-# Terminal 3: Publish test events
-# Use your preferred method to publish events to the relay
-# The test will show events being received
-```
-
-## What the Fixes Do
-
-### Before (Broken)
-- Subscriptions dropped after ~30-60 seconds
-- Receiver channels filled up (32 event buffer)
-- Publisher timed out trying to send
-- Events stopped being delivered
-
-### After (Fixed)
-- Subscriptions stay active indefinitely
-- Per-subscription consumer goroutines
-- Channels never fill up
-- All events delivered without timeouts
-
-## Troubleshooting
-
-### "Failed to connect"
-```bash
-# Check relay is running
-ps aux | grep orly
-
-# Check port
-netstat -tlnp | grep 3334
-```
-
-### "Did not receive EOSE"
-```bash
-# Enable debug logging
-export ORLY_LOG_LEVEL=debug
-./orly
-```
-
-### Test panics
-Already fixed! The latest version includes proper error handling.
-
-## Files Changed
-
-Core fixes in these files:
-- `app/listener.go` - Subscription tracking + **concurrent message processing**
-- `app/handle-req.go` - Consumer goroutines (THE KEY FIX)
-- `app/handle-close.go` - Proper cleanup
-- `app/handle-websocket.go` - Cancel all on disconnect
-
-**Latest fix:** Message processor now handles messages concurrently (prevents queue from filling up)
-
-## Build Status
-
-✅ All code builds successfully:
-```bash
-go build -o orly                               # Relay
-go build -o subscription-test ./cmd/subscription-test  # Full test
-go build -o subscription-test-simple ./cmd/subscription-test-simple  # Simple test
-```
-
-## Quick Summary
-
-**Problem:** Receiver channels created but never consumed → filled up → timeout → subscription dropped
-
-**Solution:** Per-subscription consumer goroutines (khatru pattern) that continuously read from channels and forward events to clients
-
-**Result:** Subscriptions now stable for unlimited duration ✅

app/blossom.go

@@ -42,12 +42,23 @@ func (s *Server) blossomHandler(w http.ResponseWriter, r *http.Request) {
 	if !strings.HasPrefix(r.URL.Path, "/") {
 		r.URL.Path = "/" + r.URL.Path
 	}
-	
+
 	// Set baseURL in request context for blossom server to use
+	// Use the exported key type from the blossom package
 	baseURL := s.ServiceURL(r) + "/blossom"
-	type baseURLKey struct{}
-	r = r.WithContext(context.WithValue(r.Context(), baseURLKey{}, baseURL))
-	
+	r = r.WithContext(context.WithValue(r.Context(), blossom.BaseURLKey{}, baseURL))
+
+	s.blossomServer.Handler().ServeHTTP(w, r)
+}
+
+// blossomRootHandler handles blossom requests at root level (for clients like Jumble)
+// Note: Even though requests come to root-level paths like /upload, we return URLs
+// with /blossom prefix because that's where the blob download handlers are registered.
+func (s *Server) blossomRootHandler(w http.ResponseWriter, r *http.Request) {
+	// Set baseURL with /blossom prefix so returned blob URLs point to working handlers
+	baseURL := s.ServiceURL(r) + "/blossom"
+	r = r.WithContext(context.WithValue(r.Context(), blossom.BaseURLKey{}, baseURL))
+
 	s.blossomServer.Handler().ServeHTTP(w, r)
 }
 

app/config/config.go

@@ -1,5 +1,13 @@
 // Package config provides a go-simpler.org/env configuration table and helpers
 // for working with the list of key/value lists stored in .env files.
+//
+// IMPORTANT: This file is the SINGLE SOURCE OF TRUTH for all environment variables.
+// All configuration options MUST be defined here with proper `env` struct tags.
+// Never use os.Getenv() directly in other packages - pass configuration via structs.
+// This ensures all options appear in `./orly help` output and are documented.
+//
+// For database backends, use GetDatabaseConfigValues() to extract database-specific
+// settings, then construct a database.DatabaseConfig in the caller (e.g., main.go).
 package config
 
 import (
@@ -16,6 +24,8 @@ import (
 	"go-simpler.org/env"
 	lol "lol.mleku.dev"
 	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+	"next.orly.dev/pkg/logbuffer"
 	"next.orly.dev/pkg/version"
 )
 
@@ -33,7 +43,9 @@ type C struct {
 	DBLogLevel          string        `env:"ORLY_DB_LOG_LEVEL" default:"info" usage:"database log level: fatal error warn info debug trace"`
 	DBBlockCacheMB      int           `env:"ORLY_DB_BLOCK_CACHE_MB" default:"512" usage:"Badger block cache size in MB (higher improves read hit ratio)"`
 	DBIndexCacheMB      int           `env:"ORLY_DB_INDEX_CACHE_MB" default:"256" usage:"Badger index cache size in MB (improves index lookup performance)"`
+	DBZSTDLevel         int           `env:"ORLY_DB_ZSTD_LEVEL" default:"1" usage:"Badger ZSTD compression level (1=fast/500MB/s, 3=default, 9=best ratio, 0=disable)"`
 	LogToStdout         bool          `env:"ORLY_LOG_TO_STDOUT" default:"false" usage:"log to stdout instead of stderr"`
+	LogBufferSize       int           `env:"ORLY_LOG_BUFFER_SIZE" default:"10000" usage:"number of log entries to keep in memory for web UI viewing (0 disables)"`
 	Pprof               string        `env:"ORLY_PPROF" usage:"enable pprof in modes: cpu,memory,allocation,heap,block,goroutine,threadcreate,mutex"`
 	PprofPath           string        `env:"ORLY_PPROF_PATH" usage:"optional directory to write pprof profiles into (inside container); default is temporary dir"`
 	PprofHTTP           bool          `env:"ORLY_PPROF_HTTP" default:"false" usage:"if true, expose net/http/pprof on port 6060"`
@@ -68,14 +80,89 @@ type C struct {
 	// Spider settings
 	SpiderMode string `env:"ORLY_SPIDER_MODE" default:"none" usage:"spider mode for syncing events: none, follows"`
 
-	PolicyEnabled bool `env:"ORLY_POLICY_ENABLED" default:"false" usage:"enable policy-based event processing (configuration found in $HOME/.config/ORLY/policy.json)"`
+	// Directory Spider settings
+	DirectorySpiderEnabled  bool          `env:"ORLY_DIRECTORY_SPIDER" default:"false" usage:"enable directory spider for metadata sync (kinds 0, 3, 10000, 10002)"`
+	DirectorySpiderInterval time.Duration `env:"ORLY_DIRECTORY_SPIDER_INTERVAL" default:"24h" usage:"how often to run directory spider"`
+	DirectorySpiderMaxHops  int           `env:"ORLY_DIRECTORY_SPIDER_HOPS" default:"3" usage:"maximum hops for relay discovery from seed users"`
+
+	PolicyEnabled bool   `env:"ORLY_POLICY_ENABLED" default:"false" usage:"enable policy-based event processing (default config: $HOME/.config/ORLY/policy.json)"`
+	PolicyPath    string `env:"ORLY_POLICY_PATH" usage:"ABSOLUTE path to policy configuration file (MUST start with /); overrides default location; relative paths are rejected"`
+
+	// NIP-43 Relay Access Metadata and Requests
+	NIP43Enabled          bool          `env:"ORLY_NIP43_ENABLED" default:"false" usage:"enable NIP-43 relay access metadata and invite system"`
+	NIP43PublishEvents    bool          `env:"ORLY_NIP43_PUBLISH_EVENTS" default:"true" usage:"publish kind 8000/8001 events when members are added/removed"`
+	NIP43PublishMemberList bool         `env:"ORLY_NIP43_PUBLISH_MEMBER_LIST" default:"true" usage:"publish kind 13534 membership list events"`
+	NIP43InviteExpiry     time.Duration `env:"ORLY_NIP43_INVITE_EXPIRY" default:"24h" usage:"how long invite codes remain valid"`
+
+	// Database configuration
+	DBType              string `env:"ORLY_DB_TYPE" default:"badger" usage:"database backend to use: badger or neo4j"`
+	QueryCacheDisabled  bool   `env:"ORLY_QUERY_CACHE_DISABLED" default:"true" usage:"disable query cache to reduce memory usage (trades memory for query performance)"`
+	QueryCacheSizeMB    int    `env:"ORLY_QUERY_CACHE_SIZE_MB" default:"512" usage:"query cache size in MB (caches database query results for faster REQ responses)"`
+	QueryCacheMaxAge    string `env:"ORLY_QUERY_CACHE_MAX_AGE" default:"5m" usage:"maximum age for cached query results (e.g., 5m, 10m, 1h)"`
+
+	// Neo4j configuration (only used when ORLY_DB_TYPE=neo4j)
+	Neo4jURI      string `env:"ORLY_NEO4J_URI" default:"bolt://localhost:7687" usage:"Neo4j bolt URI (only used when ORLY_DB_TYPE=neo4j)"`
+	Neo4jUser     string `env:"ORLY_NEO4J_USER" default:"neo4j" usage:"Neo4j authentication username (only used when ORLY_DB_TYPE=neo4j)"`
+	Neo4jPassword string `env:"ORLY_NEO4J_PASSWORD" default:"password" usage:"Neo4j authentication password (only used when ORLY_DB_TYPE=neo4j)"`
+
+	// Neo4j driver tuning (memory and connection management)
+	Neo4jMaxConnPoolSize   int `env:"ORLY_NEO4J_MAX_CONN_POOL" default:"25" usage:"max Neo4j connection pool size (driver default: 100, lower reduces memory)"`
+	Neo4jFetchSize         int `env:"ORLY_NEO4J_FETCH_SIZE" default:"1000" usage:"max records per fetch batch (prevents memory overflow, -1=fetch all)"`
+	Neo4jMaxTxRetrySeconds int `env:"ORLY_NEO4J_MAX_TX_RETRY_SEC" default:"30" usage:"max seconds for retryable transaction attempts"`
+	Neo4jQueryResultLimit  int `env:"ORLY_NEO4J_QUERY_RESULT_LIMIT" default:"10000" usage:"max results returned per query (prevents unbounded memory usage, 0=unlimited)"`
+
+	// Advanced database tuning
+	SerialCachePubkeys  int `env:"ORLY_SERIAL_CACHE_PUBKEYS" default:"100000" usage:"max pubkeys to cache for compact event storage (default: 100000, ~3.2MB memory)"`
+	SerialCacheEventIds int `env:"ORLY_SERIAL_CACHE_EVENT_IDS" default:"500000" usage:"max event IDs to cache for compact event storage (default: 500000, ~16MB memory)"`
+
+	// Connection concurrency control
+	MaxHandlersPerConnection int `env:"ORLY_MAX_HANDLERS_PER_CONN" default:"100" usage:"max concurrent message handlers per WebSocket connection (limits goroutine growth under load)"`
+
+	// Adaptive rate limiting (PID-controlled)
+	RateLimitEnabled            bool    `env:"ORLY_RATE_LIMIT_ENABLED" default:"true" usage:"enable adaptive PID-controlled rate limiting for database operations"`
+	RateLimitTargetMB           int     `env:"ORLY_RATE_LIMIT_TARGET_MB" default:"0" usage:"target memory limit in MB (0=auto-detect: 66% of available, min 500MB)"`
+	RateLimitWriteKp            float64 `env:"ORLY_RATE_LIMIT_WRITE_KP" default:"0.5" usage:"PID proportional gain for write operations"`
+	RateLimitWriteKi            float64 `env:"ORLY_RATE_LIMIT_WRITE_KI" default:"0.1" usage:"PID integral gain for write operations"`
+	RateLimitWriteKd            float64 `env:"ORLY_RATE_LIMIT_WRITE_KD" default:"0.05" usage:"PID derivative gain for write operations (filtered)"`
+	RateLimitReadKp             float64 `env:"ORLY_RATE_LIMIT_READ_KP" default:"0.3" usage:"PID proportional gain for read operations"`
+	RateLimitReadKi             float64 `env:"ORLY_RATE_LIMIT_READ_KI" default:"0.05" usage:"PID integral gain for read operations"`
+	RateLimitReadKd             float64 `env:"ORLY_RATE_LIMIT_READ_KD" default:"0.02" usage:"PID derivative gain for read operations (filtered)"`
+	RateLimitMaxWriteMs         int     `env:"ORLY_RATE_LIMIT_MAX_WRITE_MS" default:"1000" usage:"maximum delay for write operations in milliseconds"`
+	RateLimitMaxReadMs          int     `env:"ORLY_RATE_LIMIT_MAX_READ_MS" default:"500" usage:"maximum delay for read operations in milliseconds"`
+	RateLimitWriteTarget        float64 `env:"ORLY_RATE_LIMIT_WRITE_TARGET" default:"0.85" usage:"PID setpoint for writes (throttle when load exceeds this, 0.0-1.0)"`
+	RateLimitReadTarget         float64 `env:"ORLY_RATE_LIMIT_READ_TARGET" default:"0.90" usage:"PID setpoint for reads (throttle when load exceeds this, 0.0-1.0)"`
+	RateLimitEmergencyThreshold float64 `env:"ORLY_RATE_LIMIT_EMERGENCY_THRESHOLD" default:"1.167" usage:"memory pressure ratio (target+1/6) to trigger emergency mode with aggressive throttling"`
+	RateLimitRecoveryThreshold  float64 `env:"ORLY_RATE_LIMIT_RECOVERY_THRESHOLD" default:"0.833" usage:"memory pressure ratio (target-1/6) below which emergency mode exits (hysteresis)"`
+	RateLimitEmergencyMaxMs     int     `env:"ORLY_RATE_LIMIT_EMERGENCY_MAX_MS" default:"5000" usage:"maximum delay for writes in emergency mode (milliseconds)"`
 
 	// TLS configuration
 	TLSDomains []string `env:"ORLY_TLS_DOMAINS" usage:"comma-separated list of domains to respond to for TLS"`
 	Certs      []string `env:"ORLY_CERTS" usage:"comma-separated list of paths to certificate root names (e.g., /path/to/cert will load /path/to/cert.pem and /path/to/cert.key)"`
 
+	// WireGuard VPN configuration (for secure bunker access)
+	WGEnabled  bool   `env:"ORLY_WG_ENABLED" default:"false" usage:"enable embedded WireGuard VPN server for private bunker access"`
+	WGPort     int    `env:"ORLY_WG_PORT" default:"51820" usage:"UDP port for WireGuard VPN server"`
+	WGEndpoint string `env:"ORLY_WG_ENDPOINT" usage:"public IP/domain for WireGuard endpoint (required if WG enabled)"`
+	WGNetwork  string `env:"ORLY_WG_NETWORK" default:"10.73.0.0/16" usage:"WireGuard internal network CIDR"`
+
+	// NIP-46 Bunker configuration (remote signing service)
+	BunkerEnabled bool `env:"ORLY_BUNKER_ENABLED" default:"false" usage:"enable NIP-46 bunker signing service (requires WireGuard)"`
+	BunkerPort    int  `env:"ORLY_BUNKER_PORT" default:"3335" usage:"internal port for bunker WebSocket (only accessible via WireGuard)"`
+
+	// Cashu access token configuration (NIP-XX)
+	CashuEnabled     bool   `env:"ORLY_CASHU_ENABLED" default:"false" usage:"enable Cashu blind signature tokens for access control"`
+	CashuTokenTTL    string `env:"ORLY_CASHU_TOKEN_TTL" default:"168h" usage:"token validity duration (default: 1 week)"`
+	CashuKeysetTTL   string `env:"ORLY_CASHU_KEYSET_TTL" default:"168h" usage:"keyset active signing period (default: 1 week)"`
+	CashuVerifyTTL   string `env:"ORLY_CASHU_VERIFY_TTL" default:"504h" usage:"keyset verification period (default: 3 weeks)"`
+	CashuScopes      string `env:"ORLY_CASHU_SCOPES" default:"relay,nip46" usage:"comma-separated list of allowed token scopes"`
+	CashuReauthorize bool   `env:"ORLY_CASHU_REAUTHORIZE" default:"true" usage:"re-check ACL on each token verification for stateless revocation"`
+
 	// Cluster replication configuration
 	ClusterPropagatePrivilegedEvents bool `env:"ORLY_CLUSTER_PROPAGATE_PRIVILEGED_EVENTS" default:"true" usage:"propagate privileged events (DMs, gift wraps, etc.) to relay peers for replication"`
+
+	// ServeMode is set programmatically by the 'serve' subcommand to grant full owner
+	// access to all users (no env tag - internal use only)
+	ServeMode bool
 }
 
 // New creates and initializes a new configuration object for the relay
@@ -118,6 +205,21 @@ func New() (cfg *C, err error) {
 	if cfg.LogToStdout {
 		lol.Writer = os.Stdout
 	}
+	// Initialize log buffer for web UI viewing
+	if cfg.LogBufferSize > 0 {
+		logbuffer.Init(cfg.LogBufferSize)
+		logbuffer.SetCurrentLevel(cfg.LogLevel)
+		lol.Writer = logbuffer.NewBufferedWriter(lol.Writer, logbuffer.GlobalBuffer)
+		// Reinitialize the loggers to use the new wrapped Writer
+		// The lol.Main logger is initialized in init() with os.Stderr directly,
+		// so we need to recreate it with the new Writer
+		l, c, e := lol.New(lol.Writer, 2)
+		lol.Main.Log = l
+		lol.Main.Check = c
+		lol.Main.Errorf = e
+		// Also update the log package convenience variables
+		log.F, log.E, log.W, log.I, log.D, log.T = l.F, l.E, l.W, l.I, l.D, l.T
+	}
 	lol.SetLogLevel(cfg.LogLevel)
 	return
 }
@@ -181,6 +283,36 @@ func IdentityRequested() (requested bool) {
 	return
 }
 
+// ServeRequested checks if the first command line argument is "serve" and returns
+// whether the relay should start in ephemeral serve mode with RAM-based storage.
+//
+// Return Values
+//   - requested: true if the 'serve' subcommand was provided, false otherwise.
+func ServeRequested() (requested bool) {
+	if len(os.Args) > 1 {
+		switch strings.ToLower(os.Args[1]) {
+		case "serve":
+			requested = true
+		}
+	}
+	return
+}
+
+// VersionRequested checks if the first command line argument is "version" and returns
+// whether the version should be printed and the program should exit.
+//
+// Return Values
+//   - requested: true if the 'version' subcommand was provided, false otherwise.
+func VersionRequested() (requested bool) {
+	if len(os.Args) > 1 {
+		switch strings.ToLower(os.Args[1]) {
+		case "version", "-v", "--v", "-version", "--version":
+			requested = true
+		}
+	}
+	return
+}
+
 // KV is a key/value pair.
 type KV struct{ Key, Value string }
 
@@ -312,10 +444,15 @@ func PrintHelp(cfg *C, printer io.Writer) {
 	)
 	_, _ = fmt.Fprintf(
 		printer,
-		`Usage: %s [env|help]
+		`Usage: %s [env|help|identity|serve|version]
 
 - env: print environment variables configuring %s
 - help: print this help text
+- identity: print the relay identity secret and public key
+- serve: start ephemeral relay with RAM-based storage at /dev/shm/orlyserve
+         listening on 0.0.0.0:10547 with 'none' ACL mode (open relay)
+         useful for testing and benchmarking
+- version: print version and exit (also: -v, --v, -version, --version)
 
 `,
 		cfg.AppName, cfg.AppName,
@@ -329,3 +466,127 @@ func PrintHelp(cfg *C, printer io.Writer) {
 	PrintEnv(cfg, printer)
 	fmt.Fprintln(printer)
 }
+
+// GetDatabaseConfigValues returns the database configuration values as individual fields.
+// This avoids circular imports with pkg/database while allowing main.go to construct
+// a database.DatabaseConfig with the correct type.
+func (cfg *C) GetDatabaseConfigValues() (
+	dataDir, logLevel string,
+	blockCacheMB, indexCacheMB, queryCacheSizeMB int,
+	queryCacheMaxAge time.Duration,
+	queryCacheDisabled bool,
+	serialCachePubkeys, serialCacheEventIds int,
+	zstdLevel int,
+	neo4jURI, neo4jUser, neo4jPassword string,
+	neo4jMaxConnPoolSize, neo4jFetchSize, neo4jMaxTxRetrySeconds, neo4jQueryResultLimit int,
+) {
+	// Parse query cache max age from string to duration
+	queryCacheMaxAge = 5 * time.Minute // Default
+	if cfg.QueryCacheMaxAge != "" {
+		if duration, err := time.ParseDuration(cfg.QueryCacheMaxAge); err == nil {
+			queryCacheMaxAge = duration
+		}
+	}
+
+	return cfg.DataDir, cfg.DBLogLevel,
+		cfg.DBBlockCacheMB, cfg.DBIndexCacheMB, cfg.QueryCacheSizeMB,
+		queryCacheMaxAge,
+		cfg.QueryCacheDisabled,
+		cfg.SerialCachePubkeys, cfg.SerialCacheEventIds,
+		cfg.DBZSTDLevel,
+		cfg.Neo4jURI, cfg.Neo4jUser, cfg.Neo4jPassword,
+		cfg.Neo4jMaxConnPoolSize, cfg.Neo4jFetchSize, cfg.Neo4jMaxTxRetrySeconds, cfg.Neo4jQueryResultLimit
+}
+
+// GetRateLimitConfigValues returns the rate limiting configuration values.
+// This avoids circular imports with pkg/ratelimit while allowing main.go to construct
+// a ratelimit.Config with the correct type.
+func (cfg *C) GetRateLimitConfigValues() (
+	enabled bool,
+	targetMB int,
+	writeKp, writeKi, writeKd float64,
+	readKp, readKi, readKd float64,
+	maxWriteMs, maxReadMs int,
+	writeTarget, readTarget float64,
+	emergencyThreshold, recoveryThreshold float64,
+	emergencyMaxMs int,
+) {
+	return cfg.RateLimitEnabled,
+		cfg.RateLimitTargetMB,
+		cfg.RateLimitWriteKp, cfg.RateLimitWriteKi, cfg.RateLimitWriteKd,
+		cfg.RateLimitReadKp, cfg.RateLimitReadKi, cfg.RateLimitReadKd,
+		cfg.RateLimitMaxWriteMs, cfg.RateLimitMaxReadMs,
+		cfg.RateLimitWriteTarget, cfg.RateLimitReadTarget,
+		cfg.RateLimitEmergencyThreshold, cfg.RateLimitRecoveryThreshold,
+		cfg.RateLimitEmergencyMaxMs
+}
+
+// GetWireGuardConfigValues returns the WireGuard VPN configuration values.
+// This avoids circular imports with pkg/wireguard while allowing main.go to construct
+// the WireGuard server configuration.
+func (cfg *C) GetWireGuardConfigValues() (
+	enabled bool,
+	port int,
+	endpoint string,
+	network string,
+	bunkerEnabled bool,
+	bunkerPort int,
+) {
+	return cfg.WGEnabled,
+		cfg.WGPort,
+		cfg.WGEndpoint,
+		cfg.WGNetwork,
+		cfg.BunkerEnabled,
+		cfg.BunkerPort
+}
+
+// GetCashuConfigValues returns the Cashu access token configuration values.
+// This avoids circular imports with pkg/cashu while allowing main.go to construct
+// the Cashu issuer/verifier configuration.
+func (cfg *C) GetCashuConfigValues() (
+	enabled bool,
+	tokenTTL time.Duration,
+	keysetTTL time.Duration,
+	verifyTTL time.Duration,
+	scopes []string,
+	reauthorize bool,
+) {
+	// Parse token TTL
+	tokenTTL = 168 * time.Hour // Default: 1 week
+	if cfg.CashuTokenTTL != "" {
+		if d, err := time.ParseDuration(cfg.CashuTokenTTL); err == nil {
+			tokenTTL = d
+		}
+	}
+
+	// Parse keyset TTL
+	keysetTTL = 168 * time.Hour // Default: 1 week
+	if cfg.CashuKeysetTTL != "" {
+		if d, err := time.ParseDuration(cfg.CashuKeysetTTL); err == nil {
+			keysetTTL = d
+		}
+	}
+
+	// Parse verify TTL
+	verifyTTL = 504 * time.Hour // Default: 3 weeks
+	if cfg.CashuVerifyTTL != "" {
+		if d, err := time.ParseDuration(cfg.CashuVerifyTTL); err == nil {
+			verifyTTL = d
+		}
+	}
+
+	// Parse scopes
+	if cfg.CashuScopes != "" {
+		scopes = strings.Split(cfg.CashuScopes, ",")
+		for i := range scopes {
+			scopes[i] = strings.TrimSpace(scopes[i])
+		}
+	}
+
+	return cfg.CashuEnabled,
+		tokenTTL,
+		keysetTTL,
+		verifyTTL,
+		scopes,
+		cfg.CashuReauthorize
+}

app/handle-auth.go

@@ -3,15 +3,27 @@ package app
 import (
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/okenvelope"
-	"next.orly.dev/pkg/protocol/auth"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/okenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/reason"
+	"git.mleku.dev/mleku/nostr/protocol/auth"
 )
 
+// zeroEventID is used for OK responses when we cannot parse the event ID
+var zeroEventID = make([]byte, 32)
+
 func (l *Listener) HandleAuth(b []byte) (err error) {
 	var rem []byte
 	env := authenvelope.NewResponse()
 	if rem, err = env.Unmarshal(b); chk.E(err) {
+		// NIP-42: AUTH messages MUST be answered with an OK message
+		// For parse failures, use zero event ID
+		log.E.F("%s AUTH unmarshal failed: %v", l.remote, err)
+		if writeErr := okenvelope.NewFrom(
+			zeroEventID, false, reason.Error.F("failed to parse auth event: %s", err),
+		).Write(l); chk.E(writeErr) {
+			return writeErr
+		}
 		return
 	}
 	defer func() {
@@ -60,7 +72,7 @@ func (l *Listener) HandleAuth(b []byte) (err error) {
 // handleFirstTimeUser checks if user is logging in for first time and creates welcome note
 func (l *Listener) handleFirstTimeUser(pubkey []byte) {
 	// Check if this is a first-time user
-	isFirstTime, err := l.Server.D.IsFirstTimeUser(pubkey)
+	isFirstTime, err := l.Server.DB.IsFirstTimeUser(pubkey)
 	if err != nil {
 		log.E.F("failed to check first-time user status: %v", err)
 		return

app/handle-bunker.go

@@ -0,0 +1,83 @@
+package app
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"git.mleku.dev/mleku/nostr/encoders/bech32encoding"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+)
+
+// BunkerInfoResponse is returned by the /api/bunker/info endpoint.
+type BunkerInfoResponse struct {
+	RelayURL     string `json:"relay_url"`      // WebSocket URL for NIP-46 connections
+	RelayNpub    string `json:"relay_npub"`     // Relay's npub
+	RelayPubkey  string `json:"relay_pubkey"`   // Relay's hex pubkey
+	ACLMode      string `json:"acl_mode"`       // Current ACL mode
+	CashuEnabled bool   `json:"cashu_enabled"`  // Whether CAT is required
+	Available    bool   `json:"available"`      // Whether bunker is available
+}
+
+// handleBunkerInfo returns bunker connection information.
+// This is a public endpoint that doesn't require authentication.
+func (s *Server) handleBunkerInfo(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Get relay identity
+	relaySecret, err := s.DB.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		log.E.F("failed to get relay identity: %v", err)
+		http.Error(w, "Failed to get relay identity", http.StatusInternalServerError)
+		return
+	}
+
+	// Derive public key
+	sign, err := p8k.New()
+	if chk.E(err) {
+		http.Error(w, "Failed to create signer", http.StatusInternalServerError)
+		return
+	}
+	if err := sign.InitSec(relaySecret); chk.E(err) {
+		http.Error(w, "Failed to initialize signer", http.StatusInternalServerError)
+		return
+	}
+	relayPubkey := sign.Pub()
+	relayPubkeyHex := hex.Enc(relayPubkey)
+
+	// Encode as npub
+	relayNpubBytes, err := bech32encoding.BinToNpub(relayPubkey)
+	relayNpub := string(relayNpubBytes)
+	if chk.E(err) {
+		relayNpub = relayPubkeyHex // Fallback to hex
+	}
+
+	// Build WebSocket URL from service URL
+	serviceURL := s.ServiceURL(r)
+	wsURL := strings.Replace(serviceURL, "https://", "wss://", 1)
+	wsURL = strings.Replace(wsURL, "http://", "ws://", 1)
+
+	// Check if Cashu is enabled
+	cashuEnabled := s.CashuIssuer != nil
+
+	// Bunker is available when ACL mode is not "none"
+	available := s.Config.ACLMode != "none"
+
+	resp := BunkerInfoResponse{
+		RelayURL:     wsURL,
+		RelayNpub:    relayNpub,
+		RelayPubkey:  relayPubkeyHex,
+		ACLMode:      s.Config.ACLMode,
+		CashuEnabled: cashuEnabled,
+		Available:    available,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}

app/handle-cashu.go

@@ -0,0 +1,144 @@
+package app
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+
+	"git.mleku.dev/mleku/nostr/httpauth"
+	"next.orly.dev/pkg/cashu/issuer"
+	"next.orly.dev/pkg/cashu/keyset"
+	"next.orly.dev/pkg/cashu/token"
+)
+
+// CashuMintRequest is the request body for token issuance.
+type CashuMintRequest struct {
+	BlindedMessage string  `json:"blinded_message"` // Hex-encoded blinded point B_
+	Scope          string  `json:"scope"`           // Token scope (e.g., "relay", "nip46")
+	Kinds          []int   `json:"kinds,omitempty"` // Permitted event kinds
+	KindRanges     [][]int `json:"kind_ranges,omitempty"` // Permitted kind ranges
+}
+
+// CashuMintResponse is the response body for token issuance.
+type CashuMintResponse struct {
+	BlindedSignature string `json:"blinded_signature"` // Hex-encoded blinded signature C_
+	KeysetID         string `json:"keyset_id"`         // Keyset ID used
+	Expiry           int64  `json:"expiry"`            // Token expiration timestamp
+	MintPubkey       string `json:"mint_pubkey"`       // Hex-encoded mint public key
+}
+
+// handleCashuMint handles POST /cashu/mint - issues a new token.
+func (s *Server) handleCashuMint(w http.ResponseWriter, r *http.Request) {
+	// Check if Cashu is enabled
+	if s.CashuIssuer == nil {
+		http.Error(w, "Cashu tokens not enabled", http.StatusNotImplemented)
+		return
+	}
+
+	// Require NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		http.Error(w, "NIP-98 authentication required", http.StatusUnauthorized)
+		return
+	}
+
+	// Parse request body
+	var req CashuMintRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	// Decode blinded message from hex
+	blindedMsg, err := hex.DecodeString(req.BlindedMessage)
+	if err != nil {
+		http.Error(w, "Invalid blinded_message: must be hex", http.StatusBadRequest)
+		return
+	}
+
+	// Default scope
+	if req.Scope == "" {
+		req.Scope = token.ScopeRelay
+	}
+
+	// Issue token
+	issueReq := &issuer.IssueRequest{
+		BlindedMessage: blindedMsg,
+		Pubkey:         pubkey,
+		Scope:          req.Scope,
+		Kinds:          req.Kinds,
+		KindRanges:     req.KindRanges,
+	}
+
+	resp, err := s.CashuIssuer.Issue(r.Context(), issueReq, r.RemoteAddr)
+	if err != nil {
+		log.W.F("Cashu mint failed for %x: %v", pubkey[:8], err)
+		http.Error(w, err.Error(), http.StatusForbidden)
+		return
+	}
+
+	log.D.F("Cashu token issued for %x, scope=%s, keyset=%s", pubkey[:8], req.Scope, resp.KeysetID)
+
+	// Return response
+	mintResp := CashuMintResponse{
+		BlindedSignature: hex.EncodeToString(resp.BlindedSignature),
+		KeysetID:         resp.KeysetID,
+		Expiry:           resp.Expiry,
+		MintPubkey:       hex.EncodeToString(resp.MintPubkey),
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(mintResp)
+}
+
+// handleCashuKeysets handles GET /cashu/keysets - returns available keysets.
+func (s *Server) handleCashuKeysets(w http.ResponseWriter, r *http.Request) {
+	if s.CashuIssuer == nil {
+		http.Error(w, "Cashu tokens not enabled", http.StatusNotImplemented)
+		return
+	}
+
+	infos := s.CashuIssuer.GetKeysetInfo()
+
+	type KeysetsResponse struct {
+		Keysets []keyset.KeysetInfo `json:"keysets"`
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(KeysetsResponse{Keysets: infos})
+}
+
+// handleCashuInfo handles GET /cashu/info - returns mint information.
+func (s *Server) handleCashuInfo(w http.ResponseWriter, r *http.Request) {
+	if s.CashuIssuer == nil {
+		http.Error(w, "Cashu tokens not enabled", http.StatusNotImplemented)
+		return
+	}
+
+	info := s.CashuIssuer.GetMintInfo(s.Config.AppName)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(info)
+}
+
+// CashuTokenTTL returns the configured token TTL.
+func (s *Server) CashuTokenTTL() time.Duration {
+	enabled, tokenTTL, _, _, _, _ := s.Config.GetCashuConfigValues()
+	if !enabled {
+		return 0
+	}
+	return tokenTTL
+}
+
+// CashuKeysetTTL returns the configured keyset TTL.
+func (s *Server) CashuKeysetTTL() time.Duration {
+	enabled, _, keysetTTL, _, _, _ := s.Config.GetCashuConfigValues()
+	if !enabled {
+		return 0
+	}
+	return keysetTTL
+}

app/handle-close.go

@@ -5,7 +5,7 @@ import (
 
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
-	"next.orly.dev/pkg/encoders/envelopes/closeenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/closeenvelope"
 )
 
 // HandleClose processes a CLOSE envelope by unmarshalling the request,

app/handle-count.go

@@ -9,10 +9,10 @@ import (
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/crypto/ec/schnorr"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/countenvelope"
-	"next.orly.dev/pkg/utils/normalize"
+	"git.mleku.dev/mleku/nostr/crypto/ec/schnorr"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/countenvelope"
+	"git.mleku.dev/mleku/nostr/utils/normalize"
 )
 
 // HandleCount processes a COUNT envelope by parsing the request, verifying
@@ -78,7 +78,7 @@ func (l *Listener) HandleCount(msg []byte) (err error) {
 		}
 		var cnt int
 		var a bool
-		cnt, a, err = l.D.CountEvents(ctx, f)
+		cnt, a, err = l.DB.CountEvents(ctx, f)
 		if chk.E(err) {
 			return
 		}

app/handle-delete.go

@@ -4,28 +4,36 @@ import (
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/database/indexes/types"
-	"next.orly.dev/pkg/encoders/envelopes/eventenvelope"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/filter"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/ints"
-	"next.orly.dev/pkg/encoders/kind"
-	"next.orly.dev/pkg/encoders/tag"
-	"next.orly.dev/pkg/encoders/tag/atag"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/ints"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"git.mleku.dev/mleku/nostr/encoders/tag/atag"
 	utils "next.orly.dev/pkg/utils"
 )
 
 func (l *Listener) GetSerialsFromFilter(f *filter.F) (
 	sers types.Uint40s, err error,
 ) {
-	return l.D.GetSerialsFromFilter(f)
+	return l.DB.GetSerialsFromFilter(f)
 }
 
 func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 	log.I.F("HandleDelete: processing delete event %0x from pubkey %0x", env.E.ID, env.E.Pubkey)
 	log.I.F("HandleDelete: delete event tags: %d tags", len(*env.E.Tags))
 	for i, t := range *env.E.Tags {
-		log.I.F("HandleDelete: tag %d: %s = %s", i, string(t.Key()), string(t.Value()))
+		// Use ValueHex() for e/p tags to properly display binary-encoded values
+		key := string(t.Key())
+		var val string
+		if key == "e" || key == "p" {
+			val = string(t.ValueHex()) // Properly converts binary to hex
+		} else {
+			val = string(t.Value())
+		}
+		log.I.F("HandleDelete: tag %d: %s = %s", i, key, val)
 	}
 
 	// Debug: log admin and owner lists
@@ -89,7 +97,7 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 				if len(sers) > 0 {
 					for _, s := range sers {
 						var ev *event.E
-						if ev, err = l.FetchEventBySerial(s); chk.E(err) {
+						if ev, err = l.DB.FetchEventBySerial(s); chk.E(err) {
 							continue
 						}
 						// Only delete events that match the a-tag criteria:
@@ -127,7 +135,7 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 							hex.Enc(ev.ID), at.Kind.K, hex.Enc(at.Pubkey),
 							string(at.DTag), ev.CreatedAt, env.E.CreatedAt,
 						)
-						if err = l.DeleteEventBySerial(
+						if err = l.DB.DeleteEventBySerial(
 							l.Ctx(), s, ev,
 						); chk.E(err) {
 							log.E.F("HandleDelete: failed to delete event %s: %v", hex.Enc(ev.ID), err)
@@ -142,20 +150,21 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 		// if e tags are found, delete them if the author is signer, or one of
 		// the owners is signer
 		if utils.FastEqual(t.Key(), []byte("e")) {
-			val := t.Value()
-			if len(val) == 0 {
+			// Use ValueHex() which properly handles both binary-encoded and hex string formats
+			hexVal := t.ValueHex()
+			if len(hexVal) == 0 {
 				log.W.F("HandleDelete: empty e-tag value")
 				continue
 			}
-			log.I.F("HandleDelete: processing e-tag with value: %s", string(val))
-			var dst []byte
-			if b, e := hex.Dec(string(val)); chk.E(e) {
-				log.E.F("HandleDelete: failed to decode hex event ID %s: %v", string(val), e)
+			log.I.F("HandleDelete: processing e-tag event ID: %s", string(hexVal))
+
+			// Decode hex to binary for filter
+			dst, e := hex.Dec(string(hexVal))
+			if chk.E(e) {
+				log.E.F("HandleDelete: failed to decode event ID %s: %v", string(hexVal), e)
 				continue
-			} else {
-				dst = b
-				log.I.F("HandleDelete: decoded event ID: %0x", dst)
 			}
+
 			f := &filter.F{
 				Ids: tag.NewFromBytesSlice(dst),
 			}
@@ -164,14 +173,14 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 				log.E.F("HandleDelete: failed to get serials from filter: %v", err)
 				continue
 			}
-			log.I.F("HandleDelete: found %d serials for event ID %s", len(sers), string(val))
+			log.I.F("HandleDelete: found %d serials for event ID %0x", len(sers), dst)
 			// if found, delete them
 			if len(sers) > 0 {
 				// there should be only one event per serial, so we can just
 				// delete them all
 				for _, s := range sers {
 					var ev *event.E
-					if ev, err = l.FetchEventBySerial(s); chk.E(err) {
+					if ev, err = l.DB.FetchEventBySerial(s); chk.E(err) {
 						continue
 					}
 					// Debug: log the comparison details
@@ -199,7 +208,7 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 						"HandleDelete: deleting event %s by authorized user %s",
 						hex.Enc(ev.ID), hex.Enc(env.E.Pubkey),
 					)
-					if err = l.DeleteEventBySerial(l.Ctx(), s, ev); chk.E(err) {
+					if err = l.DB.DeleteEventBySerial(l.Ctx(), s, ev); chk.E(err) {
 						log.E.F("HandleDelete: failed to delete event %s: %v", hex.Enc(ev.ID), err)
 						continue
 					}
@@ -233,7 +242,7 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 				// delete old ones, so we can just delete them all
 				for _, s := range sers {
 					var ev *event.E
-					if ev, err = l.FetchEventBySerial(s); chk.E(err) {
+					if ev, err = l.DB.FetchEventBySerial(s); chk.E(err) {
 						continue
 					}
 					// For admin/owner deletes: allow deletion regardless of pubkey match
@@ -246,7 +255,7 @@ func (l *Listener) HandleDelete(env *eventenvelope.Submission) (err error) {
 						"HandleDelete: deleting event %s via k-tag by authorized user %s",
 						hex.Enc(ev.ID), hex.Enc(env.E.Pubkey),
 					)
-					if err = l.DeleteEventBySerial(l.Ctx(), s, ev); chk.E(err) {
+					if err = l.DB.DeleteEventBySerial(l.Ctx(), s, ev); chk.E(err) {
 						log.E.F("HandleDelete: failed to delete event %s: %v", hex.Enc(ev.ID), err)
 						continue
 					}

app/handle-event-types.go

@@ -0,0 +1,72 @@
+package app
+
+import (
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/okenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/reason"
+	"next.orly.dev/pkg/event/authorization"
+	"next.orly.dev/pkg/event/routing"
+	"next.orly.dev/pkg/event/validation"
+)
+
+// sendValidationError sends an appropriate OK response for a validation failure.
+func (l *Listener) sendValidationError(env eventenvelope.I, result validation.Result) error {
+	var r []byte
+	switch result.Code {
+	case validation.ReasonBlocked:
+		r = reason.Blocked.F(result.Msg)
+	case validation.ReasonInvalid:
+		r = reason.Invalid.F(result.Msg)
+	case validation.ReasonError:
+		r = reason.Error.F(result.Msg)
+	default:
+		r = reason.Error.F(result.Msg)
+	}
+	return okenvelope.NewFrom(env.Id(), false, r).Write(l)
+}
+
+// sendAuthorizationDenied sends an appropriate OK response for an authorization denial.
+func (l *Listener) sendAuthorizationDenied(env eventenvelope.I, decision authorization.Decision) error {
+	var r []byte
+	if decision.RequireAuth {
+		r = reason.AuthRequired.F(decision.DenyReason)
+	} else {
+		r = reason.Blocked.F(decision.DenyReason)
+	}
+	return okenvelope.NewFrom(env.Id(), false, r).Write(l)
+}
+
+// sendRoutingError sends an appropriate OK response for a routing error.
+func (l *Listener) sendRoutingError(env eventenvelope.I, result routing.Result) error {
+	if result.Error != nil {
+		return okenvelope.NewFrom(env.Id(), false, reason.Error.F(result.Error.Error())).Write(l)
+	}
+	return nil
+}
+
+// sendProcessingError sends an appropriate OK response for a processing failure.
+func (l *Listener) sendProcessingError(env eventenvelope.I, msg string) error {
+	return okenvelope.NewFrom(env.Id(), false, reason.Error.F(msg)).Write(l)
+}
+
+// sendProcessingBlocked sends an appropriate OK response for a blocked event.
+func (l *Listener) sendProcessingBlocked(env eventenvelope.I, msg string) error {
+	return okenvelope.NewFrom(env.Id(), false, reason.Blocked.F(msg)).Write(l)
+}
+
+// sendRawValidationError sends an OK response for raw JSON validation failure (before unmarshal).
+// Since we don't have an event ID at this point, we pass nil.
+func (l *Listener) sendRawValidationError(result validation.Result) error {
+	var r []byte
+	switch result.Code {
+	case validation.ReasonBlocked:
+		r = reason.Blocked.F(result.Msg)
+	case validation.ReasonInvalid:
+		r = reason.Invalid.F(result.Msg)
+	case validation.ReasonError:
+		r = reason.Error.F(result.Msg)
+	default:
+		r = reason.Error.F(result.Msg)
+	}
+	return okenvelope.NewFrom(nil, false, r).Write(l)
+}

app/handle-event.go

@@ -2,24 +2,39 @@ package app
 
 import (
 	"context"
-	"fmt"
-	"strings"
-	"time"
 
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/eventenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/okenvelope"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/kind"
-	"next.orly.dev/pkg/encoders/reason"
-	"next.orly.dev/pkg/utils"
+	"next.orly.dev/pkg/cashu/token"
+	"next.orly.dev/pkg/event/routing"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/noticeenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/okenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/reason"
+	"next.orly.dev/pkg/protocol/nip43"
 )
 
 func (l *Listener) HandleEvent(msg []byte) (err error) {
 	log.D.F("HandleEvent: START handling event: %s", msg)
+
+	// 1. Raw JSON validation (before unmarshal) - use validation service
+	if result := l.eventValidator.ValidateRawJSON(msg); !result.Valid {
+		log.W.F("HandleEvent: rejecting event with validation error: %s", result.Msg)
+		// Send NOTICE to alert client developers about the issue
+		if noticeErr := noticeenvelope.NewFrom(result.Msg).Write(l); noticeErr != nil {
+			log.E.F("failed to send NOTICE for validation error: %v", noticeErr)
+		}
+		// Send OK false with the error message
+		if err = l.sendRawValidationError(result); chk.E(err) {
+			return
+		}
+		return nil
+	}
+
 	// decode the envelope
 	env := eventenvelope.NewSubmission()
 	log.I.F("HandleEvent: received event message length: %d", len(msg))
@@ -109,415 +124,186 @@ func (l *Listener) HandleEvent(msg []byte) (err error) {
 		}
 	}
 
-	// Check if policy is enabled and process event through it
-	if l.policyManager != nil && l.policyManager.Manager != nil && l.policyManager.Manager.IsEnabled() {
-
-		// Check policy for write access
-		allowed, policyErr := l.policyManager.CheckPolicy("write", env.E, l.authedPubkey.Load(), l.remote)
-		if chk.E(policyErr) {
-			log.E.F("policy check failed: %v", policyErr)
-			if err = Ok.Error(
-				l, env, "policy check failed",
-			); chk.E(err) {
-				return
-			}
-			return
-		}
-
-		if !allowed {
-			log.D.F("policy rejected event %0x", env.E.ID)
-			if err = Ok.Blocked(
-				l, env, "event blocked by policy",
-			); chk.E(err) {
-				return
-			}
-			return
-		}
-
-		log.D.F("policy allowed event %0x", env.E.ID)
-
-		// Check ACL policy for managed ACL mode, but skip for peer relay sync events
-		if acl.Registry.Active.Load() == "managed" && !l.isPeerRelayPubkey(l.authedPubkey.Load()) {
-			allowed, aclErr := acl.Registry.CheckPolicy(env.E)
-			if chk.E(aclErr) {
-				log.E.F("ACL policy check failed: %v", aclErr)
-				if err = Ok.Error(
-					l, env, "ACL policy check failed",
-				); chk.E(err) {
-					return
-				}
-				return
-			}
-
-			if !allowed {
-				log.D.F("ACL policy rejected event %0x", env.E.ID)
-				if err = Ok.Blocked(
-					l, env, "event blocked by ACL policy",
-				); chk.E(err) {
-					return
-				}
-				return
-			}
-
-			log.D.F("ACL policy allowed event %0x", env.E.ID)
-		}
-	}
-
-	// check the event ID is correct
-	calculatedId := env.E.GetIDBytes()
-	if !utils.FastEqual(calculatedId, env.E.ID) {
-		if err = Ok.Invalid(
-			l, env, "event id is computed incorrectly, "+
-				"event has ID %0x, but when computed it is %0x",
-			env.E.ID, calculatedId,
-		); chk.E(err) {
-			return
-		}
-		return
-	}
-	// validate timestamp - reject events too far in the future (more than 1 hour)
-	now := time.Now().Unix()
-	if env.E.CreatedAt > now+3600 {
-		if err = Ok.Invalid(
-			l, env,
-			"timestamp too far in the future",
-		); chk.E(err) {
+	// Event validation (ID, timestamp, signature) - use validation service
+	if result := l.eventValidator.ValidateEvent(env.E); !result.Valid {
+		if err = l.sendValidationError(env, result); chk.E(err) {
 			return
 		}
 		return
 	}
 
-	// verify the signature
-	var ok bool
-	if ok, err = env.Verify(); chk.T(err) {
-		if err = Ok.Error(
-			l, env, fmt.Sprintf(
-				"failed to verify signature: %s",
-				err.Error(),
-			),
-		); chk.E(err) {
-			return
-		}
-	} else if !ok {
-		if err = Ok.Invalid(
-			l, env,
-			"signature is invalid",
-		); chk.E(err) {
-			return
-		}
-		return
-	}
-	// check permissions of user
-	log.I.F(
-		"HandleEvent: checking ACL permissions for pubkey: %s",
-		hex.Enc(l.authedPubkey.Load()),
-	)
-
-	// If ACL mode is "none" and no pubkey is set, use the event's pubkey
-	// But if auth is required or AuthToWrite is enabled, always use the authenticated pubkey
-	var pubkeyForACL []byte
-	if len(l.authedPubkey.Load()) == 0 && acl.Registry.Active.Load() == "none" && !l.Config.AuthRequired && !l.Config.AuthToWrite {
-		pubkeyForACL = env.E.Pubkey
-		log.I.F(
-			"HandleEvent: ACL mode is 'none' and auth not required, using event pubkey for ACL check: %s",
-			hex.Enc(pubkeyForACL),
-		)
-	} else {
-		pubkeyForACL = l.authedPubkey.Load()
-	}
-
-	// If auth is required or AuthToWrite is enabled but user is not authenticated, deny access
-	if (l.Config.AuthRequired || l.Config.AuthToWrite) && len(l.authedPubkey.Load()) == 0 {
-		log.D.F("HandleEvent: authentication required for write operations but user not authenticated")
-		if err = okenvelope.NewFrom(
-			env.Id(), false,
-			reason.AuthRequired.F("authentication required for write operations"),
-		).Write(l); chk.E(err) {
+	// Check Cashu token kind permissions if a token was provided
+	if l.cashuToken != nil && !l.cashuToken.IsKindPermitted(int(env.E.Kind)) {
+		log.W.F("HandleEvent: rejecting event kind %d - not permitted by Cashu token", env.E.Kind)
+		if err = Ok.Error(l, env, "event kind not permitted by access token"); chk.E(err) {
 			return
 		}
 		return
 	}
 
-	accessLevel := acl.Registry.GetAccessLevel(pubkeyForACL, l.remote)
-	log.I.F("HandleEvent: ACL access level: %s", accessLevel)
-
-	// Skip ACL check for admin/owner delete events
-	skipACLCheck := false
-	if env.E.Kind == kind.EventDeletion.K {
-		// Check if the delete event signer is admin or owner
-		for _, admin := range l.Admins {
-			if utils.FastEqual(admin, env.E.Pubkey) {
-				skipACLCheck = true
-				log.I.F("HandleEvent: admin delete event - skipping ACL check")
-				break
+	// Require Cashu token for NIP-46 events when Cashu is enabled and ACL is active
+	const kindNIP46 = 24133
+	if env.E.Kind == kindNIP46 && l.CashuVerifier != nil && l.Config.ACLMode != "none" {
+		if l.cashuToken == nil {
+			log.W.F("HandleEvent: rejecting NIP-46 event - Cashu access token required")
+			if err = Ok.Error(l, env, "restricted: NIP-46 requires Cashu access token"); chk.E(err) {
+				return
 			}
+			return
 		}
-		if !skipACLCheck {
-			for _, owner := range l.Owners {
-				if utils.FastEqual(owner, env.E.Pubkey) {
-					skipACLCheck = true
-					log.I.F("HandleEvent: owner delete event - skipping ACL check")
-					break
-				}
+		// Also verify the token has NIP-46 scope
+		if l.cashuToken.Scope != token.ScopeNIP46 && l.cashuToken.Scope != token.ScopeRelay {
+			log.W.F("HandleEvent: rejecting NIP-46 event - token scope %q not valid for NIP-46", l.cashuToken.Scope)
+			if err = Ok.Error(l, env, "restricted: access token scope not valid for NIP-46"); chk.E(err) {
+				return
 			}
+			return
 		}
 	}
 
-	if !skipACLCheck {
-		switch accessLevel {
-		case "none":
-			log.D.F(
-				"handle event: sending 'OK,false,auth-required...' to %s",
-				l.remote,
-			)
-			if err = okenvelope.NewFrom(
-				env.Id(), false,
-				reason.AuthRequired.F("auth required for write access"),
-			).Write(l); chk.E(err) {
-				// return
-			}
-			log.D.F("handle event: sending challenge to %s", l.remote)
-			if err = authenvelope.NewChallengeWith(l.challenge.Load()).
-				Write(l); chk.E(err) {
-				return
-			}
-			return
-		case "read":
-			log.D.F(
-				"handle event: sending 'OK,false,auth-required:...' to %s",
-				l.remote,
-			)
-			if err = okenvelope.NewFrom(
-				env.Id(), false,
-				reason.AuthRequired.F("auth required for write access"),
-			).Write(l); chk.E(err) {
-				return
-			}
-			log.D.F("handle event: sending challenge to %s", l.remote)
-			if err = authenvelope.NewChallengeWith(l.challenge.Load()).
-				Write(l); chk.E(err) {
-				return
-			}
-			return
-		case "blocked":
-			log.D.F(
-				"handle event: sending 'OK,false,blocked...' to %s",
-				l.remote,
-			)
-			if err = okenvelope.NewFrom(
-				env.Id(), false,
-				reason.AuthRequired.F("IP address blocked"),
-			).Write(l); chk.E(err) {
-				return
-			}
-			return
-		case "banned":
-			log.D.F(
-				"handle event: sending 'OK,false,banned...' to %s",
-				l.remote,
-			)
-			if err = okenvelope.NewFrom(
-				env.Id(), false,
-				reason.AuthRequired.F("pubkey banned"),
-			).Write(l); chk.E(err) {
-				return
-			}
-			return
-		default:
-			// user has write access or better, continue
-			log.I.F("HandleEvent: user has %s access, continuing", accessLevel)
+	// Handle NIP-43 special events before ACL checks
+	switch env.E.Kind {
+	case nip43.KindJoinRequest:
+		// Process join request and return early
+		if err = l.HandleNIP43JoinRequest(env.E); chk.E(err) {
+			log.E.F("failed to process NIP-43 join request: %v", err)
 		}
-	} else {
-		log.I.F("HandleEvent: skipping ACL check for admin/owner delete event")
-	}
-
-	// check if event is ephemeral - if so, deliver and return early
-	if kind.IsEphemeral(env.E.Kind) {
-		log.D.F("handling ephemeral event %0x (kind %d)", env.E.ID, env.E.Kind)
-		// Send OK response for ephemeral events
-		if err = Ok.Ok(l, env, ""); chk.E(err) {
-			return
-		}
-		// Deliver the event to subscribers immediately
-		clonedEvent := env.E.Clone()
-		go l.publishers.Deliver(clonedEvent)
-		log.D.F("delivered ephemeral event %0x", env.E.ID)
 		return
-	}
-	log.D.F("processing regular event %0x (kind %d)", env.E.ID, env.E.Kind)
-
-	// check for protected tag (NIP-70)
-	protectedTag := env.E.Tags.GetFirst([]byte("-"))
-	if protectedTag != nil && acl.Registry.Active.Load() != "none" {
-		// check that the pubkey of the event matches the authed pubkey
-		if !utils.FastEqual(l.authedPubkey.Load(), env.E.Pubkey) {
-			if err = Ok.Blocked(
-				l, env,
-				"protected tag may only be published by user authed to the same pubkey",
-			); chk.E(err) {
-				return
-			}
-			return
+	case nip43.KindLeaveRequest:
+		// Process leave request and return early
+		if err = l.HandleNIP43LeaveRequest(env.E); chk.E(err) {
+			log.E.F("failed to process NIP-43 leave request: %v", err)
 		}
-	}
-	// if the event is a delete, process the delete
-	log.I.F(
-		"HandleEvent: checking if event is delete - kind: %d, EventDeletion.K: %d",
-		env.E.Kind, kind.EventDeletion.K,
-	)
-	if env.E.Kind == kind.EventDeletion.K {
-		log.I.F("processing delete event %0x", env.E.ID)
-
-		// Store the delete event itself FIRST to ensure it's available for queries
-		saveCtx, cancel := context.WithTimeout(
-			context.Background(), 30*time.Second,
-		)
-		defer cancel()
-		log.I.F(
-			"attempting to save delete event %0x from pubkey %0x", env.E.ID,
-			env.E.Pubkey,
-		)
-		log.I.F("delete event pubkey hex: %s", hex.Enc(env.E.Pubkey))
-		if _, err = l.SaveEvent(saveCtx, env.E); err != nil {
-			log.E.F("failed to save delete event %0x: %v", env.E.ID, err)
-			if strings.HasPrefix(err.Error(), "blocked:") {
-				errStr := err.Error()[len("blocked: "):len(err.Error())]
-				if err = Ok.Error(
-					l, env, errStr,
-				); chk.E(err) {
-					return
-				}
-				return
-			}
-			chk.E(err)
-			return
-		}
-		log.I.F("successfully saved delete event %0x", env.E.ID)
-
-		// Now process the deletion (remove target events)
-		if err = l.HandleDelete(env); err != nil {
-			log.E.F("HandleDelete failed for event %0x: %v", env.E.ID, err)
-			if strings.HasPrefix(err.Error(), "blocked:") {
-				errStr := err.Error()[len("blocked: "):len(err.Error())]
-				if err = Ok.Error(
-					l, env, errStr,
-				); chk.E(err) {
-					return
-				}
-				return
-			}
-			// For non-blocked errors, still send OK but log the error
-			log.W.F("Delete processing failed but continuing: %v", err)
-		} else {
-			log.I.F(
-				"HandleDelete completed successfully for event %0x", env.E.ID,
-			)
-		}
-
-		// Send OK response for delete events
-		if err = Ok.Ok(l, env, ""); chk.E(err) {
-			return
-		}
-
-		// Deliver the delete event to subscribers
-		clonedEvent := env.E.Clone()
-		go l.publishers.Deliver(clonedEvent)
-		log.D.F("processed delete event %0x", env.E.ID)
 		return
-	} else {
-		// check if the event was deleted
-		// Combine admins and owners for deletion checking
-		adminOwners := append(l.Admins, l.Owners...)
-		if err = l.CheckForDeleted(env.E, adminOwners); err != nil {
-			if strings.HasPrefix(err.Error(), "blocked:") {
-				errStr := err.Error()[len("blocked: "):len(err.Error())]
-				if err = Ok.Error(
-					l, env, errStr,
-				); chk.E(err) {
-					return
-				}
-			}
-		}
-	}
-	// store the event - use a separate context to prevent cancellation issues
-	saveCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-	// log.I.F("saving event %0x, %s", env.E.ID, env.E.Serialize())
-	if _, err = l.SaveEvent(saveCtx, env.E); err != nil {
-		if strings.HasPrefix(err.Error(), "blocked:") {
-			errStr := err.Error()[len("blocked: "):len(err.Error())]
-			if err = Ok.Error(
-				l, env, errStr,
-			); chk.E(err) {
+	case kind.PolicyConfig.K:
+		// Handle policy configuration update events (kind 12345)
+		// Only policy admins can update policy configuration
+		if err = l.HandlePolicyConfigUpdate(env.E); chk.E(err) {
+			log.E.F("failed to process policy config update: %v", err)
+			if err = Ok.Error(l, env, err.Error()); chk.E(err) {
 				return
 			}
 			return
 		}
-		chk.E(err)
+		// Send OK response
+		if err = Ok.Ok(l, env, "policy configuration updated"); chk.E(err) {
+			return
+		}
 		return
-	}
-
-	// Handle relay group configuration events
-	if l.relayGroupMgr != nil {
-		if err := l.relayGroupMgr.ValidateRelayGroupEvent(env.E); err != nil {
-			log.W.F("invalid relay group config event %s: %v", hex.Enc(env.E.ID), err)
-		}
-		// Process the event and potentially update peer lists
-		if l.syncManager != nil {
-			l.relayGroupMgr.HandleRelayGroupEvent(env.E, l.syncManager)
-		}
-	}
-
-	// Handle cluster membership events (Kind 39108)
-	if env.E.Kind == 39108 && l.clusterManager != nil {
-		if err := l.clusterManager.HandleMembershipEvent(env.E); err != nil {
-			log.W.F("invalid cluster membership event %s: %v", hex.Enc(env.E.ID), err)
-		}
-	}
-
-	// Update serial for distributed synchronization
-	if l.syncManager != nil {
-		l.syncManager.UpdateSerial()
-		log.D.F("updated serial for event %s", hex.Enc(env.E.ID))
-	}
-	// Send a success response storing
-	if err = Ok.Ok(l, env, ""); chk.E(err) {
-		return
-	}
-	// Deliver the event to subscribers immediately after sending OK response
-	// Clone the event to prevent corruption when the original is freed
-	clonedEvent := env.E.Clone()
-	go l.publishers.Deliver(clonedEvent)
-	log.D.F("saved event %0x", env.E.ID)
-	var isNewFromAdmin bool
-	// Check if event is from admin or owner
-	for _, admin := range l.Admins {
-		if utils.FastEqual(admin, env.E.Pubkey) {
-			isNewFromAdmin = true
-			break
-		}
-	}
-	if !isNewFromAdmin {
-		for _, owner := range l.Owners {
-			if utils.FastEqual(owner, env.E.Pubkey) {
-				isNewFromAdmin = true
-				break
-			}
-		}
-	}
-	if isNewFromAdmin {
-		log.I.F("new event from admin %0x", env.E.Pubkey)
-		// if a follow list was saved, reconfigure ACLs now that it is persisted
-		if env.E.Kind == kind.FollowList.K ||
-			env.E.Kind == kind.RelayListMetadata.K {
-			// Run ACL reconfiguration asynchronously to prevent blocking websocket operations
+	case kind.FollowList.K:
+		// Check if this is a follow list update from a policy admin
+		// If so, refresh the policy follows cache immediately
+		if l.IsPolicyAdminFollowListEvent(env.E) {
+			// Process the follow list update (async, don't block)
 			go func() {
-				if err := acl.Registry.Configure(); chk.E(err) {
-					log.E.F("failed to reconfigure ACL: %v", err)
+				if updateErr := l.HandlePolicyAdminFollowListUpdate(env.E); updateErr != nil {
+					log.W.F("failed to update policy follows from admin follow list: %v", updateErr)
 				}
 			}()
 		}
+		// Continue with normal follow list processing (store the event)
 	}
+
+	// Authorization check (policy + ACL) - use authorization service
+	decision := l.eventAuthorizer.Authorize(env.E, l.authedPubkey.Load(), l.remote, env.E.Kind)
+	if !decision.Allowed {
+		log.D.F("HandleEvent: authorization denied: %s (requireAuth=%v)", decision.DenyReason, decision.RequireAuth)
+		if decision.RequireAuth {
+			// Send OK false with reason
+			if err = okenvelope.NewFrom(
+				env.Id(), false,
+				reason.AuthRequired.F(decision.DenyReason),
+			).Write(l); chk.E(err) {
+				return
+			}
+			// Send AUTH challenge
+			if err = authenvelope.NewChallengeWith(l.challenge.Load()).Write(l); chk.E(err) {
+				return
+			}
+		} else {
+			// Send OK false with blocked reason
+			if err = Ok.Blocked(l, env, decision.DenyReason); chk.E(err) {
+				return
+			}
+		}
+		return
+	}
+	log.I.F("HandleEvent: authorized with access level %s", decision.AccessLevel)
+
+	// Route special event kinds (ephemeral, etc.) - use routing service
+	if routeResult := l.eventRouter.Route(env.E, l.authedPubkey.Load()); routeResult.Action != routing.Continue {
+		if routeResult.Action == routing.Handled {
+			// Event fully handled by router, send OK and return
+			log.D.F("event %0x handled by router", env.E.ID)
+			if err = Ok.Ok(l, env, routeResult.Message); chk.E(err) {
+				return
+			}
+			return
+		} else if routeResult.Action == routing.Error {
+			// Router encountered an error
+			if err = l.sendRoutingError(env, routeResult); chk.E(err) {
+				return
+			}
+			return
+		}
+	}
+	log.D.F("processing regular event %0x (kind %d)", env.E.ID, env.E.Kind)
+
+	// NIP-70 protected tag validation - use validation service
+	if acl.Registry.Active.Load() != "none" {
+		if result := l.eventValidator.ValidateProtectedTag(env.E, l.authedPubkey.Load()); !result.Valid {
+			if err = l.sendValidationError(env, result); chk.E(err) {
+				return
+			}
+			return
+		}
+	}
+	// Handle delete events specially - save first, then process deletions
+	if env.E.Kind == kind.EventDeletion.K {
+		log.I.F("processing delete event %0x", env.E.ID)
+
+		// Save and deliver using processing service
+		result := l.eventProcessor.Process(context.Background(), env.E)
+		if result.Blocked {
+			if err = Ok.Error(l, env, result.BlockMsg); chk.E(err) {
+				return
+			}
+			return
+		}
+		if result.Error != nil {
+			chk.E(result.Error)
+			return
+		}
+
+		// Process deletion targets (remove referenced events)
+		if err = l.HandleDelete(env); err != nil {
+			log.W.F("HandleDelete failed for event %0x: %v", env.E.ID, err)
+		}
+
+		if err = Ok.Ok(l, env, ""); chk.E(err) {
+			return
+		}
+		log.D.F("processed delete event %0x", env.E.ID)
+		return
+	}
+	// Process event: save, run hooks, and deliver to subscribers
+	result := l.eventProcessor.Process(context.Background(), env.E)
+	if result.Blocked {
+		if err = Ok.Error(l, env, result.BlockMsg); chk.E(err) {
+			return
+		}
+		return
+	}
+	if result.Error != nil {
+		chk.E(result.Error)
+		return
+	}
+
+	// Send success response
+	if err = Ok.Ok(l, env, ""); chk.E(err) {
+		return
+	}
+	log.D.F("saved event %0x", env.E.ID)
 	return
 }
 

app/handle-logs.go

@@ -0,0 +1,185 @@
+package app
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+
+	lol "lol.mleku.dev"
+	"lol.mleku.dev/chk"
+
+	"git.mleku.dev/mleku/nostr/httpauth"
+	"next.orly.dev/pkg/acl"
+	"next.orly.dev/pkg/logbuffer"
+)
+
+// LogsResponse is the response structure for GET /api/logs
+type LogsResponse struct {
+	Logs    []logbuffer.LogEntry `json:"logs"`
+	Total   int                  `json:"total"`
+	HasMore bool                 `json:"has_more"`
+}
+
+// LogLevelResponse is the response structure for GET /api/logs/level
+type LogLevelResponse struct {
+	Level string `json:"level"`
+}
+
+// LogLevelRequest is the request structure for POST /api/logs/level
+type LogLevelRequest struct {
+	Level string `json:"level"`
+}
+
+// handleGetLogs handles GET /api/logs
+func (s *Server) handleGetLogs(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		errorMsg := "NIP-98 authentication validation failed"
+		if err != nil {
+			errorMsg = err.Error()
+		}
+		http.Error(w, errorMsg, http.StatusUnauthorized)
+		return
+	}
+
+	// Check permissions - require owner level only
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "owner" {
+		http.Error(w, "Owner permission required", http.StatusForbidden)
+		return
+	}
+
+	// Check if log buffer is available
+	if logbuffer.GlobalBuffer == nil {
+		http.Error(w, "Log buffer not enabled", http.StatusServiceUnavailable)
+		return
+	}
+
+	// Parse query parameters
+	offset := 0
+	limit := 100
+	if offsetStr := r.URL.Query().Get("offset"); offsetStr != "" {
+		if v, err := strconv.Atoi(offsetStr); err == nil && v >= 0 {
+			offset = v
+		}
+	}
+	if limitStr := r.URL.Query().Get("limit"); limitStr != "" {
+		if v, err := strconv.Atoi(limitStr); err == nil && v > 0 && v <= 500 {
+			limit = v
+		}
+	}
+
+	// Get logs from buffer
+	logs := logbuffer.GlobalBuffer.Get(offset, limit)
+	total := logbuffer.GlobalBuffer.Count()
+	hasMore := offset+len(logs) < total
+
+	response := LogsResponse{
+		Logs:    logs,
+		Total:   total,
+		HasMore: hasMore,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(response)
+}
+
+// handleClearLogs handles POST /api/logs/clear
+func (s *Server) handleClearLogs(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		errorMsg := "NIP-98 authentication validation failed"
+		if err != nil {
+			errorMsg = err.Error()
+		}
+		http.Error(w, errorMsg, http.StatusUnauthorized)
+		return
+	}
+
+	// Check permissions - require owner level only
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "owner" {
+		http.Error(w, "Owner permission required", http.StatusForbidden)
+		return
+	}
+
+	// Check if log buffer is available
+	if logbuffer.GlobalBuffer == nil {
+		http.Error(w, "Log buffer not enabled", http.StatusServiceUnavailable)
+		return
+	}
+
+	// Clear the buffer
+	logbuffer.GlobalBuffer.Clear()
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handleLogLevel handles GET and POST /api/logs/level
+func (s *Server) handleLogLevel(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		s.handleGetLogLevel(w, r)
+	case http.MethodPost:
+		s.handleSetLogLevel(w, r)
+	default:
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+	}
+}
+
+// handleGetLogLevel handles GET /api/logs/level
+func (s *Server) handleGetLogLevel(w http.ResponseWriter, r *http.Request) {
+	// No auth required for reading log level
+	level := logbuffer.GetCurrentLevel()
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(LogLevelResponse{Level: level})
+}
+
+// handleSetLogLevel handles POST /api/logs/level
+func (s *Server) handleSetLogLevel(w http.ResponseWriter, r *http.Request) {
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		errorMsg := "NIP-98 authentication validation failed"
+		if err != nil {
+			errorMsg = err.Error()
+		}
+		http.Error(w, errorMsg, http.StatusUnauthorized)
+		return
+	}
+
+	// Check permissions - require owner level only
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "owner" {
+		http.Error(w, "Owner permission required", http.StatusForbidden)
+		return
+	}
+
+	// Parse request body
+	var req LogLevelRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	// Validate and set log level
+	level := logbuffer.SetCurrentLevel(req.Level)
+	lol.SetLogLevel(level)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(LogLevelResponse{Level: level})
+}

app/handle-message.go

@@ -4,66 +4,62 @@ import (
 	"fmt"
 	"strings"
 	"time"
-	"unicode"
+	"unicode/utf8"
 
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
-	"next.orly.dev/pkg/encoders/envelopes"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/closeenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/countenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/eventenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/noticeenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/reqenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/closeenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/countenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/noticeenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/reqenvelope"
 )
 
 // validateJSONMessage checks if a message contains invalid control characters
-// that would cause JSON parsing to fail
+// that would cause JSON parsing to fail. It also validates UTF-8 encoding.
 func validateJSONMessage(msg []byte) (err error) {
-	for i, b := range msg {
-		// Check for invalid control characters in JSON strings
+	// First, validate that the message is valid UTF-8
+	if !utf8.Valid(msg) {
+		return fmt.Errorf("invalid UTF-8 encoding")
+	}
+
+	// Check for invalid control characters in JSON strings
+	for i := 0; i < len(msg); i++ {
+		b := msg[i]
+
+		// Check for invalid control characters (< 32) except tab, newline, carriage return
 		if b < 32 && b != '\t' && b != '\n' && b != '\r' {
-			// Allow some control characters that might be valid in certain contexts
-			// but reject form feed (\f), backspace (\b), and other problematic ones
-			switch b {
-			case '\b', '\f', 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
-				0x0E, 0x0F, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
-				0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F:
-				return fmt.Errorf("invalid control character 0x%02X at position %d", b, i)
-			}
-		}
-		// Check for non-printable characters that might indicate binary data
-		if b > 127 && !unicode.IsPrint(rune(b)) {
-			// Allow valid UTF-8 sequences, but be suspicious of random binary data
-			if i < len(msg)-1 {
-				// Quick check: if we see a lot of high-bit characters in sequence,
-				// it might be binary data masquerading as text
-				highBitCount := 0
-				for j := i; j < len(msg) && j < i+10; j++ {
-					if msg[j] > 127 {
-						highBitCount++
-					}
-				}
-				if highBitCount > 7 { // More than 70% high-bit chars in a 10-byte window
-					return fmt.Errorf("suspicious binary data detected at position %d", i)
-				}
-			}
+			return fmt.Errorf(
+				"invalid control character 0x%02X at position %d", b, i,
+			)
 		}
 	}
 	return
 }
 
 func (l *Listener) HandleMessage(msg []byte, remote string) {
+	// Acquire read lock for message processing - allows concurrent processing
+	// but blocks during policy/follow list updates (which acquire write lock)
+	l.Server.AcquireMessageProcessingLock()
+	defer l.Server.ReleaseMessageProcessingLock()
+
 	// Handle blacklisted IPs - discard messages but keep connection open until timeout
 	if l.isBlacklisted {
 		// Check if timeout has been reached
 		if time.Now().After(l.blacklistTimeout) {
-			log.W.F("blacklisted IP %s timeout reached, closing connection", remote)
+			log.W.F(
+				"blacklisted IP %s timeout reached, closing connection", remote,
+			)
 			// Close the connection by cancelling the context
 			// The websocket handler will detect this and close the connection
 			return
 		}
-		log.D.F("discarding message from blacklisted IP %s (timeout in %v)", remote, time.Until(l.blacklistTimeout))
+		log.D.F(
+			"discarding message from blacklisted IP %s (timeout in %v)", remote,
+			time.Until(l.blacklistTimeout),
+		)
 		return
 	}
 
@@ -71,13 +67,22 @@ func (l *Listener) HandleMessage(msg []byte, remote string) {
 	if len(msgPreview) > 150 {
 		msgPreview = msgPreview[:150] + "..."
 	}
-	// log.D.F("%s processing message (len=%d): %s", remote, len(msg), msgPreview)
+	log.D.F("%s processing message (len=%d): %s", remote, len(msg), msgPreview)
 
 	// Validate message for invalid characters before processing
 	if err := validateJSONMessage(msg); err != nil {
-		log.E.F("%s message validation FAILED (len=%d): %v", remote, len(msg), err)
-		if noticeErr := noticeenvelope.NewFrom(fmt.Sprintf("invalid message format: contains invalid characters: %s", msg)).Write(l); noticeErr != nil {
-			log.E.F("%s failed to send validation error notice: %v", remote, noticeErr)
+		log.E.F(
+			"%s message validation FAILED (len=%d): %v", remote, len(msg), err,
+		)
+		if noticeErr := noticeenvelope.NewFrom(
+			fmt.Sprintf(
+				"invalid message format: contains invalid characters: %s", msg,
+			),
+		).Write(l); noticeErr != nil {
+			log.E.F(
+				"%s failed to send validation error notice: %v", remote,
+				noticeErr,
+			)
 		}
 		return
 	}
@@ -140,9 +145,11 @@ func (l *Listener) HandleMessage(msg []byte, remote string) {
 	if err != nil {
 		// Don't log context cancellation errors as they're expected during shutdown
 		if !strings.Contains(err.Error(), "context canceled") {
-			log.E.F("%s message processing FAILED (type=%s): %v", remote, t, err)
+			log.E.F(
+				"%s message processing FAILED (type=%s): %v", remote, t, err,
+			)
 			// Don't log message preview as it may contain binary data
- 			// Send error notice to client (use generic message to avoid control chars in errors)
+			// Send error notice to client (use generic message to avoid control chars in errors)
 			noticeMsg := fmt.Sprintf("%s processing failed", t)
 			if noticeErr := noticeenvelope.NewFrom(noticeMsg).Write(l); noticeErr != nil {
 				log.E.F(

app/handle-nip43.go

@@ -0,0 +1,254 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+	"next.orly.dev/pkg/acl"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/okenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"next.orly.dev/pkg/protocol/nip43"
+)
+
+// HandleNIP43JoinRequest processes a kind 28934 join request
+func (l *Listener) HandleNIP43JoinRequest(ev *event.E) error {
+	log.I.F("handling NIP-43 join request from %s", hex.Enc(ev.Pubkey))
+
+	// Validate the join request
+	inviteCode, valid, reason := nip43.ValidateJoinRequest(ev)
+	if !valid {
+		log.W.F("invalid join request: %s", reason)
+		return l.sendOKResponse(ev.ID, false, fmt.Sprintf("restricted: %s", reason))
+	}
+
+	// Check if user is already a member
+	isMember, err := l.DB.IsNIP43Member(ev.Pubkey)
+	if chk.E(err) {
+		log.E.F("error checking membership: %v", err)
+		return l.sendOKResponse(ev.ID, false, "error: internal server error")
+	}
+
+	if isMember {
+		log.I.F("user %s is already a member", hex.Enc(ev.Pubkey))
+		return l.sendOKResponse(ev.ID, true, "duplicate: you are already a member of this relay")
+	}
+
+	// Validate the invite code
+	validCode, reason := l.Server.InviteManager.ValidateAndConsume(inviteCode, ev.Pubkey)
+
+	if !validCode {
+		log.W.F("invalid or expired invite code: %s - %s", inviteCode, reason)
+		return l.sendOKResponse(ev.ID, false, fmt.Sprintf("restricted: %s", reason))
+	}
+
+	// Add the member
+	if err = l.DB.AddNIP43Member(ev.Pubkey, inviteCode); chk.E(err) {
+		log.E.F("error adding member: %v", err)
+		return l.sendOKResponse(ev.ID, false, "error: failed to add member")
+	}
+
+	log.I.F("successfully added member %s via invite code", hex.Enc(ev.Pubkey))
+
+	// Publish kind 8000 "add member" event if configured
+	if l.Config.NIP43PublishEvents {
+		if err = l.publishAddUserEvent(ev.Pubkey); chk.E(err) {
+			log.W.F("failed to publish add user event: %v", err)
+		}
+	}
+
+	// Update membership list if configured
+	if l.Config.NIP43PublishMemberList {
+		if err = l.publishMembershipList(); chk.E(err) {
+			log.W.F("failed to publish membership list: %v", err)
+		}
+	}
+
+	relayURL := l.Config.RelayURL
+	if relayURL == "" {
+		relayURL = fmt.Sprintf("wss://%s:%d", l.Config.Listen, l.Config.Port)
+	}
+
+	return l.sendOKResponse(ev.ID, true, fmt.Sprintf("welcome to %s!", relayURL))
+}
+
+// HandleNIP43LeaveRequest processes a kind 28936 leave request
+func (l *Listener) HandleNIP43LeaveRequest(ev *event.E) error {
+	log.I.F("handling NIP-43 leave request from %s", hex.Enc(ev.Pubkey))
+
+	// Validate the leave request
+	valid, reason := nip43.ValidateLeaveRequest(ev)
+	if !valid {
+		log.W.F("invalid leave request: %s", reason)
+		return l.sendOKResponse(ev.ID, false, fmt.Sprintf("error: %s", reason))
+	}
+
+	// Check if user is a member
+	isMember, err := l.DB.IsNIP43Member(ev.Pubkey)
+	if chk.E(err) {
+		log.E.F("error checking membership: %v", err)
+		return l.sendOKResponse(ev.ID, false, "error: internal server error")
+	}
+
+	if !isMember {
+		log.I.F("user %s is not a member", hex.Enc(ev.Pubkey))
+		return l.sendOKResponse(ev.ID, true, "you are not a member of this relay")
+	}
+
+	// Remove the member
+	if err = l.DB.RemoveNIP43Member(ev.Pubkey); chk.E(err) {
+		log.E.F("error removing member: %v", err)
+		return l.sendOKResponse(ev.ID, false, "error: failed to remove member")
+	}
+
+	log.I.F("successfully removed member %s", hex.Enc(ev.Pubkey))
+
+	// Publish kind 8001 "remove member" event if configured
+	if l.Config.NIP43PublishEvents {
+		if err = l.publishRemoveUserEvent(ev.Pubkey); chk.E(err) {
+			log.W.F("failed to publish remove user event: %v", err)
+		}
+	}
+
+	// Update membership list if configured
+	if l.Config.NIP43PublishMemberList {
+		if err = l.publishMembershipList(); chk.E(err) {
+			log.W.F("failed to publish membership list: %v", err)
+		}
+	}
+
+	return l.sendOKResponse(ev.ID, true, "you have been removed from this relay")
+}
+
+// HandleNIP43InviteRequest processes a kind 28935 invite request (REQ subscription)
+func (s *Server) HandleNIP43InviteRequest(pubkey []byte) (*event.E, error) {
+	log.I.F("generating NIP-43 invite for pubkey %s", hex.Enc(pubkey))
+
+	// Check if requester has permission to request invites
+	// This could be based on ACL, admins, etc.
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, "")
+	if accessLevel != "admin" && accessLevel != "owner" {
+		log.W.F("unauthorized invite request from %s (level: %s)", hex.Enc(pubkey), accessLevel)
+		return nil, fmt.Errorf("unauthorized: only admins can request invites")
+	}
+
+	// Generate a new invite code
+	code, err := s.InviteManager.GenerateCode()
+	if chk.E(err) {
+		return nil, err
+	}
+
+	// Get relay identity
+	relaySecret, err := s.db.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		return nil, err
+	}
+
+	// Build the invite event
+	inviteEvent, err := nip43.BuildInviteEvent(relaySecret, code)
+	if chk.E(err) {
+		return nil, err
+	}
+
+	log.I.F("generated invite code for %s", hex.Enc(pubkey))
+	return inviteEvent, nil
+}
+
+// publishAddUserEvent publishes a kind 8000 add user event
+func (l *Listener) publishAddUserEvent(userPubkey []byte) error {
+	relaySecret, err := l.DB.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		return err
+	}
+
+	ev, err := nip43.BuildAddUserEvent(relaySecret, userPubkey)
+	if chk.E(err) {
+		return err
+	}
+
+	// Save to database
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if _, err = l.DB.SaveEvent(ctx, ev); chk.E(err) {
+		return err
+	}
+
+	// Publish to subscribers
+	l.publishers.Deliver(ev)
+
+	log.I.F("published kind 8000 add user event for %s", hex.Enc(userPubkey))
+	return nil
+}
+
+// publishRemoveUserEvent publishes a kind 8001 remove user event
+func (l *Listener) publishRemoveUserEvent(userPubkey []byte) error {
+	relaySecret, err := l.DB.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		return err
+	}
+
+	ev, err := nip43.BuildRemoveUserEvent(relaySecret, userPubkey)
+	if chk.E(err) {
+		return err
+	}
+
+	// Save to database
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if _, err = l.DB.SaveEvent(ctx, ev); chk.E(err) {
+		return err
+	}
+
+	// Publish to subscribers
+	l.publishers.Deliver(ev)
+
+	log.I.F("published kind 8001 remove user event for %s", hex.Enc(userPubkey))
+	return nil
+}
+
+// publishMembershipList publishes a kind 13534 membership list event
+func (l *Listener) publishMembershipList() error {
+	// Get all members
+	members, err := l.DB.GetAllNIP43Members()
+	if chk.E(err) {
+		return err
+	}
+
+	relaySecret, err := l.DB.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		return err
+	}
+
+	ev, err := nip43.BuildMemberListEvent(relaySecret, members)
+	if chk.E(err) {
+		return err
+	}
+
+	// Save to database
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if _, err = l.DB.SaveEvent(ctx, ev); chk.E(err) {
+		return err
+	}
+
+	// Publish to subscribers
+	l.publishers.Deliver(ev)
+
+	log.I.F("published kind 13534 membership list event with %d members", len(members))
+	return nil
+}
+
+// sendOKResponse sends an OK envelope response
+func (l *Listener) sendOKResponse(eventID []byte, accepted bool, message string) error {
+	// Ensure message doesn't have "restricted: " prefix if already present
+	if accepted && strings.HasPrefix(message, "restricted: ") {
+		message = strings.TrimPrefix(message, "restricted: ")
+	}
+
+	env := okenvelope.NewFrom(eventID, accepted, []byte(message))
+	return env.Write(l)
+}

app/handle-nip43_test.go

@@ -0,0 +1,600 @@
+package app
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"next.orly.dev/app/config"
+	"next.orly.dev/pkg/acl"
+	"git.mleku.dev/mleku/nostr/crypto/keys"
+	"next.orly.dev/pkg/database"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
+	"next.orly.dev/pkg/protocol/nip43"
+	"next.orly.dev/pkg/protocol/publish"
+)
+
+// setupTestListener creates a test listener with NIP-43 enabled
+func setupTestListener(t *testing.T) (*Listener, *database.D, func()) {
+	tempDir, err := os.MkdirTemp("", "nip43_handler_test_*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	db, err := database.New(ctx, cancel, tempDir, "info")
+	if err != nil {
+		os.RemoveAll(tempDir)
+		t.Fatalf("failed to open database: %v", err)
+	}
+
+	cfg := &config.C{
+		NIP43Enabled:           true,
+		NIP43PublishEvents:     true,
+		NIP43PublishMemberList: true,
+		NIP43InviteExpiry:      24 * time.Hour,
+		RelayURL:               "wss://test.relay",
+		Listen:                 "localhost",
+		Port:                   3334,
+		ACLMode:                "none",
+	}
+
+	server := &Server{
+		Ctx:           ctx,
+		Config:        cfg,
+		DB:            db,
+		publishers:    publish.New(NewPublisher(ctx)),
+		InviteManager: nip43.NewInviteManager(cfg.NIP43InviteExpiry),
+		cfg:           cfg,
+		db:            db,
+	}
+
+	// Configure ACL registry
+	acl.Registry.SetMode(cfg.ACLMode)
+	if err = acl.Registry.Configure(cfg, db, ctx); err != nil {
+		db.Close()
+		os.RemoveAll(tempDir)
+		t.Fatalf("failed to configure ACL: %v", err)
+	}
+
+	listener := &Listener{
+		Server:         server,
+		ctx:            ctx,
+		writeChan:      make(chan publish.WriteRequest, 100),
+		writeDone:      make(chan struct{}),
+		messageQueue:   make(chan messageRequest, 100),
+		processingDone: make(chan struct{}),
+		subscriptions:  make(map[string]context.CancelFunc),
+	}
+
+	// Start write worker and message processor
+	go listener.writeWorker()
+	go listener.messageProcessor()
+
+	cleanup := func() {
+		// Close listener channels
+		close(listener.writeChan)
+		<-listener.writeDone
+		close(listener.messageQueue)
+		<-listener.processingDone
+		db.Close()
+		os.RemoveAll(tempDir)
+	}
+
+	return listener, db, cleanup
+}
+
+// TestHandleNIP43JoinRequest_ValidRequest tests a successful join request
+func TestHandleNIP43JoinRequest_ValidRequest(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Generate invite code
+	code, err := listener.Server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	// Create join request event
+	ev := event.New()
+	ev.Kind = nip43.KindJoinRequest
+	copy(ev.Pubkey, userPubkey)
+	ev.Tags = tag.NewS()
+	ev.Tags.Append(tag.NewFromAny("-"))
+	ev.Tags.Append(tag.NewFromAny("claim", code))
+	ev.CreatedAt = time.Now().Unix()
+	ev.Content = []byte("")
+
+	// Sign event
+	if err = ev.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Handle join request
+	err = listener.HandleNIP43JoinRequest(ev)
+	if err != nil {
+		t.Fatalf("failed to handle join request: %v", err)
+	}
+
+	// Verify user was added to database
+	isMember, err := db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if !isMember {
+		t.Error("user was not added as member")
+	}
+
+	// Verify membership details
+	membership, err := db.GetNIP43Membership(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to get membership: %v", err)
+	}
+	if membership.InviteCode != code {
+		t.Errorf("wrong invite code stored: got %s, want %s", membership.InviteCode, code)
+	}
+}
+
+// TestHandleNIP43JoinRequest_InvalidCode tests join request with invalid code
+func TestHandleNIP43JoinRequest_InvalidCode(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Create join request with invalid code
+	ev := event.New()
+	ev.Kind = nip43.KindJoinRequest
+	copy(ev.Pubkey, userPubkey)
+	ev.Tags = tag.NewS()
+	ev.Tags.Append(tag.NewFromAny("-"))
+	ev.Tags.Append(tag.NewFromAny("claim", "invalid-code-123"))
+	ev.CreatedAt = time.Now().Unix()
+	ev.Content = []byte("")
+
+	if err = ev.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Handle join request - should succeed but not add member
+	err = listener.HandleNIP43JoinRequest(ev)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+
+	// Verify user was NOT added
+	isMember, err := db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if isMember {
+		t.Error("user was incorrectly added as member with invalid code")
+	}
+}
+
+// TestHandleNIP43JoinRequest_DuplicateMember tests join request from existing member
+func TestHandleNIP43JoinRequest_DuplicateMember(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Add user directly to database
+	err = db.AddNIP43Member(userPubkey, "original-code")
+	if err != nil {
+		t.Fatalf("failed to add member: %v", err)
+	}
+
+	// Generate new invite code
+	code, err := listener.Server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	// Create join request
+	ev := event.New()
+	ev.Kind = nip43.KindJoinRequest
+	copy(ev.Pubkey, userPubkey)
+	ev.Tags = tag.NewS()
+	ev.Tags.Append(tag.NewFromAny("-"))
+	ev.Tags.Append(tag.NewFromAny("claim", code))
+	ev.CreatedAt = time.Now().Unix()
+	ev.Content = []byte("")
+
+	if err = ev.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Handle join request - should handle gracefully
+	err = listener.HandleNIP43JoinRequest(ev)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+
+	// Verify original membership is unchanged
+	membership, err := db.GetNIP43Membership(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to get membership: %v", err)
+	}
+	if membership.InviteCode != "original-code" {
+		t.Errorf("invite code was changed: got %s, want original-code", membership.InviteCode)
+	}
+}
+
+// TestHandleNIP43LeaveRequest_ValidRequest tests a successful leave request
+func TestHandleNIP43LeaveRequest_ValidRequest(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Add user as member
+	err = db.AddNIP43Member(userPubkey, "test-code")
+	if err != nil {
+		t.Fatalf("failed to add member: %v", err)
+	}
+
+	// Create leave request
+	ev := event.New()
+	ev.Kind = nip43.KindLeaveRequest
+	copy(ev.Pubkey, userPubkey)
+	ev.Tags = tag.NewS()
+	ev.Tags.Append(tag.NewFromAny("-"))
+	ev.CreatedAt = time.Now().Unix()
+	ev.Content = []byte("")
+
+	if err = ev.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Handle leave request
+	err = listener.HandleNIP43LeaveRequest(ev)
+	if err != nil {
+		t.Fatalf("failed to handle leave request: %v", err)
+	}
+
+	// Verify user was removed
+	isMember, err := db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if isMember {
+		t.Error("user was not removed")
+	}
+}
+
+// TestHandleNIP43LeaveRequest_NonMember tests leave request from non-member
+func TestHandleNIP43LeaveRequest_NonMember(t *testing.T) {
+	listener, _, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user (not a member)
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Create leave request
+	ev := event.New()
+	ev.Kind = nip43.KindLeaveRequest
+	copy(ev.Pubkey, userPubkey)
+	ev.Tags = tag.NewS()
+	ev.Tags.Append(tag.NewFromAny("-"))
+	ev.CreatedAt = time.Now().Unix()
+	ev.Content = []byte("")
+
+	if err = ev.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Handle leave request - should handle gracefully
+	err = listener.HandleNIP43LeaveRequest(ev)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+}
+
+// TestHandleNIP43InviteRequest_ValidRequest tests invite request from admin
+func TestHandleNIP43InviteRequest_ValidRequest(t *testing.T) {
+	listener, _, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate admin user
+	adminSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate admin secret: %v", err)
+	}
+	adminSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = adminSigner.InitSec(adminSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	adminPubkey := adminSigner.Pub()
+
+	// Add admin to config and reconfigure ACL
+	adminHex := hex.Enc(adminPubkey)
+	listener.Server.Config.Admins = []string{adminHex}
+	acl.Registry.SetMode("none")
+	if err = acl.Registry.Configure(listener.Server.Config, listener.Server.DB, listener.ctx); err != nil {
+		t.Fatalf("failed to reconfigure ACL: %v", err)
+	}
+
+	// Handle invite request
+	inviteEvent, err := listener.Server.HandleNIP43InviteRequest(adminPubkey)
+	if err != nil {
+		t.Fatalf("failed to handle invite request: %v", err)
+	}
+
+	// Verify invite event
+	if inviteEvent == nil {
+		t.Fatal("invite event is nil")
+	}
+	if inviteEvent.Kind != nip43.KindInviteReq {
+		t.Errorf("wrong event kind: got %d, want %d", inviteEvent.Kind, nip43.KindInviteReq)
+	}
+
+	// Verify claim tag
+	claimTag := inviteEvent.Tags.GetFirst([]byte("claim"))
+	if claimTag == nil {
+		t.Fatal("missing claim tag")
+	}
+	if claimTag.Len() < 2 {
+		t.Fatal("claim tag has no value")
+	}
+}
+
+// TestHandleNIP43InviteRequest_Unauthorized tests invite request from non-admin
+func TestHandleNIP43InviteRequest_Unauthorized(t *testing.T) {
+	listener, _, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate regular user (not admin)
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Handle invite request - should fail
+	_, err = listener.Server.HandleNIP43InviteRequest(userPubkey)
+	if err == nil {
+		t.Fatal("expected error for unauthorized user")
+	}
+}
+
+// TestJoinAndLeaveFlow tests the complete join and leave flow
+func TestJoinAndLeaveFlow(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	// Generate test user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+	if err = userSigner.InitSec(userSecret); err != nil {
+		t.Fatalf("failed to initialize signer: %v", err)
+	}
+	userPubkey := userSigner.Pub()
+
+	// Step 1: Generate invite code
+	code, err := listener.Server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	// Step 2: User sends join request
+	joinEv := event.New()
+	joinEv.Kind = nip43.KindJoinRequest
+	copy(joinEv.Pubkey, userPubkey)
+	joinEv.Tags = tag.NewS()
+	joinEv.Tags.Append(tag.NewFromAny("-"))
+	joinEv.Tags.Append(tag.NewFromAny("claim", code))
+	joinEv.CreatedAt = time.Now().Unix()
+	joinEv.Content = []byte("")
+	if err = joinEv.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign join event: %v", err)
+	}
+
+	err = listener.HandleNIP43JoinRequest(joinEv)
+	if err != nil {
+		t.Fatalf("failed to handle join request: %v", err)
+	}
+
+	// Verify user is member
+	isMember, err := db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership after join: %v", err)
+	}
+	if !isMember {
+		t.Fatal("user is not a member after join")
+	}
+
+	// Step 3: User sends leave request
+	leaveEv := event.New()
+	leaveEv.Kind = nip43.KindLeaveRequest
+	copy(leaveEv.Pubkey, userPubkey)
+	leaveEv.Tags = tag.NewS()
+	leaveEv.Tags.Append(tag.NewFromAny("-"))
+	leaveEv.CreatedAt = time.Now().Unix()
+	leaveEv.Content = []byte("")
+	if err = leaveEv.Sign(userSigner); err != nil {
+		t.Fatalf("failed to sign leave event: %v", err)
+	}
+
+	err = listener.HandleNIP43LeaveRequest(leaveEv)
+	if err != nil {
+		t.Fatalf("failed to handle leave request: %v", err)
+	}
+
+	// Verify user is no longer member
+	isMember, err = db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership after leave: %v", err)
+	}
+	if isMember {
+		t.Fatal("user is still a member after leave")
+	}
+}
+
+// TestMultipleUsersJoining tests multiple users joining concurrently
+func TestMultipleUsersJoining(t *testing.T) {
+	listener, db, cleanup := setupTestListener(t)
+	defer cleanup()
+
+	userCount := 10
+	done := make(chan bool, userCount)
+
+	for i := 0; i < userCount; i++ {
+		go func(index int) {
+			// Generate user
+			userSecret, err := keys.GenerateSecretKey()
+			if err != nil {
+				t.Errorf("failed to generate user secret %d: %v", index, err)
+				done <- false
+				return
+			}
+			userSigner, err := p8k.New()
+			if err != nil {
+				t.Errorf("failed to create signer %d: %v", index, err)
+				done <- false
+				return
+			}
+			if err = userSigner.InitSec(userSecret); err != nil {
+				t.Errorf("failed to initialize signer %d: %v", index, err)
+				done <- false
+				return
+			}
+			userPubkey := userSigner.Pub()
+
+			// Generate invite code
+			code, err := listener.Server.InviteManager.GenerateCode()
+			if err != nil {
+				t.Errorf("failed to generate invite code %d: %v", index, err)
+				done <- false
+				return
+			}
+
+			// Create join request
+			joinEv := event.New()
+			joinEv.Kind = nip43.KindJoinRequest
+			copy(joinEv.Pubkey, userPubkey)
+			joinEv.Tags = tag.NewS()
+			joinEv.Tags.Append(tag.NewFromAny("-"))
+			joinEv.Tags.Append(tag.NewFromAny("claim", code))
+			joinEv.CreatedAt = time.Now().Unix()
+			joinEv.Content = []byte("")
+			if err = joinEv.Sign(userSigner); err != nil {
+				t.Errorf("failed to sign event %d: %v", index, err)
+				done <- false
+				return
+			}
+
+			// Handle join request
+			if err = listener.HandleNIP43JoinRequest(joinEv); err != nil {
+				t.Errorf("failed to handle join request %d: %v", index, err)
+				done <- false
+				return
+			}
+
+			done <- true
+		}(i)
+	}
+
+	// Wait for all goroutines
+	successCount := 0
+	for i := 0; i < userCount; i++ {
+		if <-done {
+			successCount++
+		}
+	}
+
+	if successCount != userCount {
+		t.Errorf("not all users joined successfully: %d/%d", successCount, userCount)
+	}
+
+	// Verify member count
+	members, err := db.GetAllNIP43Members()
+	if err != nil {
+		t.Fatalf("failed to get all members: %v", err)
+	}
+
+	if len(members) != successCount {
+		t.Errorf("wrong member count: got %d, want %d", len(members), successCount)
+	}
+}

app/handle-nip86.go

@@ -8,7 +8,7 @@ import (
 	"lol.mleku.dev/chk"
 	"next.orly.dev/pkg/acl"
 	"next.orly.dev/pkg/database"
-	"next.orly.dev/pkg/protocol/httpauth"
+	"git.mleku.dev/mleku/nostr/httpauth"
 )
 
 // NIP86Request represents a NIP-86 JSON-RPC request

app/handle-nip86_minimal_test.go

@@ -35,7 +35,7 @@ func TestHandleNIP86Management_Basic(t *testing.T) {
 	// Setup server
 	server := &Server{
 		Config: cfg,
-		D:      db,
+		DB:     db,
 		Admins: [][]byte{[]byte("admin1")},
 		Owners: [][]byte{[]byte("owner1")},
 	}

app/handle-policy-config.go

@@ -0,0 +1,345 @@
+package app
+
+import (
+	"bytes"
+	"fmt"
+
+	"lol.mleku.dev/log"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+)
+
+// HandlePolicyConfigUpdate processes kind 12345 policy configuration events.
+// Owners and policy admins can update policy configuration, with different permissions:
+//
+// OWNERS can:
+//   - Modify all fields including owners and policy_admins
+//   - But owners list must remain non-empty (to prevent lockout)
+//
+// POLICY ADMINS can:
+//   - Extend rules (add to allow lists, add new kinds, add blacklists)
+//   - CANNOT modify owners or policy_admins (protected fields)
+//   - CANNOT reduce owner-granted permissions
+//
+// Process flow:
+// 1. Check if sender is owner or policy admin
+// 2. Validate JSON with appropriate rules for the sender type
+// 3. Pause ALL message processing (lock mutex)
+// 4. Reload policy (pause policy engine, update, save, resume)
+// 5. Resume message processing (unlock mutex)
+//
+// The message processing mutex is already released by the caller (HandleEvent),
+// so we acquire it ourselves for the critical section.
+func (l *Listener) HandlePolicyConfigUpdate(ev *event.E) error {
+	log.I.F("received policy config update from pubkey: %s", hex.Enc(ev.Pubkey))
+
+	// 1. Verify sender is owner or policy admin
+	if l.policyManager == nil {
+		return fmt.Errorf("policy system is not enabled")
+	}
+
+	isOwner := l.policyManager.IsOwner(ev.Pubkey)
+	isAdmin := l.policyManager.IsPolicyAdmin(ev.Pubkey)
+
+	if !isOwner && !isAdmin {
+		log.W.F("policy config update rejected: pubkey %s is not an owner or policy admin", hex.Enc(ev.Pubkey))
+		return fmt.Errorf("only owners and policy administrators can update policy configuration")
+	}
+
+	if isOwner {
+		log.I.F("owner verified: %s", hex.Enc(ev.Pubkey))
+	} else {
+		log.I.F("policy admin verified: %s", hex.Enc(ev.Pubkey))
+	}
+
+	// 2. Parse and validate JSON with appropriate validation rules
+	policyJSON := []byte(ev.Content)
+	var validationErr error
+
+	if isOwner {
+		// Owners can modify all fields, but owners list must be non-empty
+		validationErr = l.policyManager.ValidateOwnerPolicyUpdate(policyJSON)
+	} else {
+		// Policy admins have restrictions: can't modify protected fields, can't reduce permissions
+		validationErr = l.policyManager.ValidatePolicyAdminUpdate(policyJSON, ev.Pubkey)
+	}
+
+	if validationErr != nil {
+		log.E.F("policy config update validation failed: %v", validationErr)
+		return fmt.Errorf("invalid policy configuration: %v", validationErr)
+	}
+
+	log.I.F("policy config validation passed")
+
+	// Get config path for saving (uses custom path if set, otherwise default)
+	configPath := l.policyManager.ConfigPath()
+
+	// 3. Pause ALL message processing (lock mutex)
+	// Note: We need to release the RLock first (which caller holds), then acquire exclusive Lock
+	// Actually, the HandleMessage already released the lock after calling HandleEvent
+	// So we can directly acquire the exclusive lock
+	log.I.F("pausing message processing for policy update")
+	l.Server.PauseMessageProcessing()
+	defer l.Server.ResumeMessageProcessing()
+
+	// 4. Reload policy (this will pause policy engine, update, save, and resume)
+	log.I.F("applying policy configuration update")
+	var reloadErr error
+	if isOwner {
+		reloadErr = l.policyManager.ReloadAsOwner(policyJSON, configPath)
+	} else {
+		reloadErr = l.policyManager.ReloadAsPolicyAdmin(policyJSON, configPath, ev.Pubkey)
+	}
+
+	if reloadErr != nil {
+		log.E.F("policy config update failed: %v", reloadErr)
+		return fmt.Errorf("failed to apply policy configuration: %v", reloadErr)
+	}
+
+	if isOwner {
+		log.I.F("policy configuration updated successfully by owner: %s", hex.Enc(ev.Pubkey))
+	} else {
+		log.I.F("policy configuration updated successfully by policy admin: %s", hex.Enc(ev.Pubkey))
+	}
+
+	// 5. Message processing mutex will be unlocked by defer
+	return nil
+}
+
+// HandlePolicyAdminFollowListUpdate processes kind 3 follow list events from policy admins.
+// When a policy admin updates their follow list, we immediately refresh the policy follows cache.
+//
+// Process flow:
+// 1. Check if sender is a policy admin
+// 2. If yes, extract p-tags from the follow list
+// 3. Pause message processing
+// 4. Aggregate all policy admin follows and update cache
+// 5. Resume message processing
+func (l *Listener) HandlePolicyAdminFollowListUpdate(ev *event.E) error {
+	// Only process if policy system is enabled
+	if l.policyManager == nil || !l.policyManager.IsEnabled() {
+		return nil // Not an error, just ignore
+	}
+
+	// Check if sender is a policy admin
+	if !l.policyManager.IsPolicyAdmin(ev.Pubkey) {
+		return nil // Not a policy admin, ignore
+	}
+
+	log.I.F("policy admin %s updated their follow list, refreshing policy follows", hex.Enc(ev.Pubkey))
+
+	// Extract p-tags from this follow list event
+	newFollows := extractFollowsFromEvent(ev)
+
+	// Pause message processing for atomic update
+	log.D.F("pausing message processing for follow list update")
+	l.Server.PauseMessageProcessing()
+	defer l.Server.ResumeMessageProcessing()
+
+	// Get all current follows from database for all policy admins
+	// For now, we'll merge the new follows with existing ones
+	// A more complete implementation would re-fetch all admin follows from DB
+	allFollows, err := l.fetchAllPolicyAdminFollows()
+	if err != nil {
+		log.W.F("failed to fetch all policy admin follows: %v, using new follows only", err)
+		allFollows = newFollows
+	} else {
+		// Merge with the new follows (deduplicated)
+		allFollows = mergeFollows(allFollows, newFollows)
+	}
+
+	// Update the policy follows cache
+	l.policyManager.UpdatePolicyFollows(allFollows)
+
+	log.I.F("policy follows cache updated with %d total pubkeys", len(allFollows))
+	return nil
+}
+
+// extractFollowsFromEvent extracts p-tag pubkeys from a kind 3 follow list event.
+// Returns binary pubkeys.
+func extractFollowsFromEvent(ev *event.E) [][]byte {
+	var follows [][]byte
+
+	pTags := ev.Tags.GetAll([]byte("p"))
+	for _, pTag := range pTags {
+		// ValueHex() handles both binary and hex storage formats automatically
+		pt, err := hex.Dec(string(pTag.ValueHex()))
+		if err != nil {
+			continue
+		}
+		follows = append(follows, pt)
+	}
+
+	return follows
+}
+
+// fetchAllPolicyAdminFollows fetches kind 3 events for all policy admins from the database
+// and aggregates their follows.
+func (l *Listener) fetchAllPolicyAdminFollows() ([][]byte, error) {
+	var allFollows [][]byte
+	seen := make(map[string]bool)
+
+	// Get policy admin pubkeys
+	admins := l.policyManager.GetPolicyAdminsBin()
+	if len(admins) == 0 {
+		return nil, fmt.Errorf("no policy admins configured")
+	}
+
+	// For each admin, query their latest kind 3 event
+	for _, adminPubkey := range admins {
+		// Build proper filter for kind 3 from this admin
+		f := filter.New()
+		f.Authors = tag.NewFromAny(adminPubkey)
+		f.Kinds = kind.NewS(kind.FollowList)
+		limit := uint(1)
+		f.Limit = &limit
+
+		// Query the database for kind 3 events from this admin
+		events, err := l.DB.QueryEvents(l.ctx, f)
+		if err != nil {
+			log.W.F("failed to query follows for admin %s: %v", hex.Enc(adminPubkey), err)
+			continue
+		}
+
+		// events is []*event.E - iterate over the slice
+		for _, ev := range events {
+			// Extract p-tags from this follow list
+			follows := extractFollowsFromEvent(ev)
+			for _, follow := range follows {
+				key := string(follow)
+				if !seen[key] {
+					seen[key] = true
+					allFollows = append(allFollows, follow)
+				}
+			}
+		}
+	}
+
+	return allFollows, nil
+}
+
+// mergeFollows merges two follow lists, removing duplicates.
+func mergeFollows(existing, newFollows [][]byte) [][]byte {
+	seen := make(map[string]bool)
+	var result [][]byte
+
+	for _, f := range existing {
+		key := string(f)
+		if !seen[key] {
+			seen[key] = true
+			result = append(result, f)
+		}
+	}
+
+	for _, f := range newFollows {
+		key := string(f)
+		if !seen[key] {
+			seen[key] = true
+			result = append(result, f)
+		}
+	}
+
+	return result
+}
+
+// IsPolicyConfigEvent returns true if the event is a policy configuration event (kind 12345)
+func IsPolicyConfigEvent(ev *event.E) bool {
+	return ev.Kind == kind.PolicyConfig.K
+}
+
+// IsPolicyAdminFollowListEvent returns true if this is a follow list event from a policy admin.
+// Used to detect when we need to refresh the policy follows cache.
+func (l *Listener) IsPolicyAdminFollowListEvent(ev *event.E) bool {
+	// Must be kind 3 (follow list)
+	if ev.Kind != kind.FollowList.K {
+		return false
+	}
+
+	// Policy system must be enabled
+	if l.policyManager == nil || !l.policyManager.IsEnabled() {
+		return false
+	}
+
+	// Sender must be a policy admin
+	return l.policyManager.IsPolicyAdmin(ev.Pubkey)
+}
+
+// isPolicyAdmin checks if a pubkey is in the list of policy admins
+func isPolicyAdmin(pubkey []byte, admins [][]byte) bool {
+	for _, admin := range admins {
+		if bytes.Equal(pubkey, admin) {
+			return true
+		}
+	}
+	return false
+}
+
+// InitializePolicyFollows loads the follow lists of all policy admins at startup.
+// This should be called after the policy manager is initialized but before
+// the relay starts accepting connections.
+// It's a method on Server so it can be called from main.go during initialization.
+func (s *Server) InitializePolicyFollows() error {
+	// Skip if policy system is not enabled
+	if s.policyManager == nil || !s.policyManager.IsEnabled() {
+		log.D.F("policy system not enabled, skipping follow list initialization")
+		return nil
+	}
+
+	// Skip if PolicyFollowWhitelistEnabled is false
+	if !s.policyManager.IsPolicyFollowWhitelistEnabled() {
+		log.D.F("policy follow whitelist not enabled, skipping follow list initialization")
+		return nil
+	}
+
+	log.I.F("initializing policy follows from database")
+
+	// Get policy admin pubkeys
+	admins := s.policyManager.GetPolicyAdminsBin()
+	if len(admins) == 0 {
+		log.W.F("no policy admins configured, skipping follow list initialization")
+		return nil
+	}
+
+	var allFollows [][]byte
+	seen := make(map[string]bool)
+
+	// For each admin, query their latest kind 3 event
+	for _, adminPubkey := range admins {
+		// Build proper filter for kind 3 from this admin
+		f := filter.New()
+		f.Authors = tag.NewFromAny(adminPubkey)
+		f.Kinds = kind.NewS(kind.FollowList)
+		limit := uint(1)
+		f.Limit = &limit
+
+		// Query the database for kind 3 events from this admin
+		events, err := s.DB.QueryEvents(s.Ctx, f)
+		if err != nil {
+			log.W.F("failed to query follows for admin %s: %v", hex.Enc(adminPubkey), err)
+			continue
+		}
+
+		// Extract p-tags from each follow list event
+		for _, ev := range events {
+			follows := extractFollowsFromEvent(ev)
+			for _, follow := range follows {
+				key := string(follow)
+				if !seen[key] {
+					seen[key] = true
+					allFollows = append(allFollows, follow)
+				}
+			}
+		}
+	}
+
+	// Update the policy follows cache
+	s.policyManager.UpdatePolicyFollows(allFollows)
+
+	log.I.F("policy follows initialized with %d pubkeys from %d admin(s)",
+		len(allFollows), len(admins))
+
+	return nil
+}

app/handle-relayinfo.go

@@ -9,9 +9,9 @@ import (
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/interfaces/signer/p8k"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/protocol/relayinfo"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/relayinfo"
 	"next.orly.dev/pkg/version"
 )
 
@@ -33,7 +33,7 @@ func (s *Server) HandleRelayInfo(w http.ResponseWriter, r *http.Request) {
 	r.Header.Set("Content-Type", "application/json")
 	log.D.Ln("handling relay information document")
 	var info *relayinfo.T
-	supportedNIPs := relayinfo.GetList(
+	nips := []relayinfo.NIP{
 		relayinfo.BasicProtocol,
 		relayinfo.Authentication,
 		relayinfo.EncryptedDirectMessage,
@@ -49,9 +49,14 @@ func (s *Server) HandleRelayInfo(w http.ResponseWriter, r *http.Request) {
 		relayinfo.ProtectedEvents,
 		relayinfo.RelayListMetadata,
 		relayinfo.SearchCapability,
-	)
+	}
+	// Add NIP-43 if enabled
+	if s.Config.NIP43Enabled {
+		nips = append(nips, relayinfo.RelayAccessMetadata)
+	}
+	supportedNIPs := relayinfo.GetList(nips...)
 	if s.Config.ACLMode != "none" {
-		supportedNIPs = relayinfo.GetList(
+		nipsACL := []relayinfo.NIP{
 			relayinfo.BasicProtocol,
 			relayinfo.Authentication,
 			relayinfo.EncryptedDirectMessage,
@@ -67,13 +72,18 @@ func (s *Server) HandleRelayInfo(w http.ResponseWriter, r *http.Request) {
 			relayinfo.ProtectedEvents,
 			relayinfo.RelayListMetadata,
 			relayinfo.SearchCapability,
-		)
+		}
+		// Add NIP-43 if enabled
+		if s.Config.NIP43Enabled {
+			nipsACL = append(nipsACL, relayinfo.RelayAccessMetadata)
+		}
+		supportedNIPs = relayinfo.GetList(nipsACL...)
 	}
 	sort.Sort(supportedNIPs)
 	log.I.Ln("supported NIPs", supportedNIPs)
 	// Get relay identity pubkey as hex
 	var relayPubkey string
-	if skb, err := s.D.GetRelayIdentitySecret(); err == nil && len(skb) == 32 {
+	if skb, err := s.DB.GetRelayIdentitySecret(); err == nil && len(skb) == 32 {
 		var sign *p8k.Signer
 		var sigErr error
 		if sign, sigErr = p8k.New(); sigErr == nil {

app/handle-req.go

@@ -12,21 +12,24 @@ import (
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/encoders/bech32encoding"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/closedenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/eoseenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/eventenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/reqenvelope"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/filter"
-	hexenc "next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/kind"
-	"next.orly.dev/pkg/encoders/reason"
-	"next.orly.dev/pkg/encoders/tag"
-	"next.orly.dev/pkg/utils"
-	"next.orly.dev/pkg/utils/normalize"
-	"next.orly.dev/pkg/utils/pointers"
+	"git.mleku.dev/mleku/nostr/encoders/bech32encoding"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/closedenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eoseenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/reqenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
+	hexenc "git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/reason"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"next.orly.dev/pkg/policy"
+	"next.orly.dev/pkg/protocol/graph"
+	"next.orly.dev/pkg/protocol/nip43"
+	"next.orly.dev/pkg/protocol/publish"
+	"git.mleku.dev/mleku/nostr/utils/normalize"
+	"git.mleku.dev/mleku/nostr/utils/pointers"
 )
 
 func (l *Listener) HandleReq(msg []byte) (err error) {
@@ -50,6 +53,51 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 			)
 		},
 	)
+
+	// NIP-46 signer-based authentication:
+	// If client is not authenticated and requests kind 24133 with exactly one #p tag,
+	// check if there's an active signer subscription for that pubkey.
+	// If so, authenticate the client as that pubkey.
+	const kindNIP46 = 24133
+	if len(l.authedPubkey.Load()) == 0 && len(*env.Filters) == 1 {
+		f := (*env.Filters)[0]
+		if f != nil && f.Kinds != nil && f.Kinds.Len() == 1 {
+			isNIP46Kind := false
+			for _, k := range f.Kinds.K {
+				if k.K == kindNIP46 {
+					isNIP46Kind = true
+					break
+				}
+			}
+			if isNIP46Kind && f.Tags != nil {
+				pTag := f.Tags.GetFirst([]byte("p"))
+				// Must have exactly one pubkey in the #p tag
+				if pTag != nil && pTag.Len() == 2 {
+					signerPubkey := pTag.Value()
+					// Convert to binary if hex
+					var signerPubkeyBin []byte
+					if len(signerPubkey) == 64 {
+						signerPubkeyBin, _ = hexenc.Dec(string(signerPubkey))
+					} else if len(signerPubkey) == 32 {
+						signerPubkeyBin = signerPubkey
+					}
+					if len(signerPubkeyBin) == 32 {
+						// Check if there's an active signer for this pubkey
+						if socketPub := l.publishers.GetSocketPublisher(); socketPub != nil {
+							if checker, ok := socketPub.(publish.NIP46SignerChecker); ok {
+								if checker.HasActiveNIP46Signer(signerPubkeyBin) {
+									log.I.F("NIP-46 auth: client %s authenticated via active signer %s",
+										l.remote, hexenc.Enc(signerPubkeyBin))
+									l.authedPubkey.Store(signerPubkeyBin)
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+
 	// send a challenge to the client to auth if an ACL is active, auth is required, or AuthToWrite is enabled
 	if len(l.authedPubkey.Load()) == 0 && (acl.Registry.Active.Load() != "none" || l.Config.AuthRequired || l.Config.AuthToWrite) {
 		if err = authenvelope.NewChallengeWith(l.challenge.Load()).
@@ -107,6 +155,126 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 			// user has read access or better, continue
 		}
 	}
+
+	// Handle NIP-43 invite request (kind 28935) - ephemeral event
+	// Check if any filter requests kind 28935
+	for _, f := range *env.Filters {
+		if f != nil && f.Kinds != nil {
+			if f.Kinds.Contains(nip43.KindInviteReq) {
+				// Generate and send invite event
+				inviteEvent, err := l.Server.HandleNIP43InviteRequest(l.authedPubkey.Load())
+				if err != nil {
+					log.W.F("failed to generate NIP-43 invite: %v", err)
+					// Send EOSE and return
+					if err = eoseenvelope.NewFrom(env.Subscription).Write(l); chk.E(err) {
+						return err
+					}
+					return nil
+				}
+
+				// Send the invite event
+				evEnv, _ := eventenvelope.NewResultWith(env.Subscription, inviteEvent)
+				if err = evEnv.Write(l); chk.E(err) {
+					return err
+				}
+
+				// Send EOSE
+				if err = eoseenvelope.NewFrom(env.Subscription).Write(l); chk.E(err) {
+					return err
+				}
+
+				log.I.F("sent NIP-43 invite event to %s", l.remote)
+				return nil
+			}
+		}
+	}
+
+	// Check for NIP-XX graph queries in filters
+	// Graph queries use the _graph filter extension to traverse the social graph
+	for _, f := range *env.Filters {
+		if f != nil && graph.IsGraphQuery(f) {
+			graphQuery, graphErr := graph.ExtractFromFilter(f)
+			if graphErr != nil {
+				log.W.F("invalid _graph query from %s: %v", l.remote, graphErr)
+				if err = closedenvelope.NewFrom(
+					env.Subscription,
+					reason.Error.F("invalid _graph query: %s", graphErr.Error()),
+				).Write(l); chk.E(err) {
+					return
+				}
+				return
+			}
+			if graphQuery != nil {
+				log.I.F("graph query from %s: method=%s seed=%s depth=%d",
+					l.remote, graphQuery.Method, graphQuery.Seed, graphQuery.Depth)
+
+				// Check if graph executor is available
+				if l.graphExecutor == nil {
+					log.W.F("graph query received but executor not initialized")
+					if err = closedenvelope.NewFrom(
+						env.Subscription,
+						reason.Error.F("graph queries not supported on this relay"),
+					).Write(l); chk.E(err) {
+						return
+					}
+					return
+				}
+
+				// Execute the graph query
+				resultEvent, execErr := l.graphExecutor.Execute(graphQuery)
+				if execErr != nil {
+					log.W.F("graph query execution failed from %s: %v", l.remote, execErr)
+					if err = closedenvelope.NewFrom(
+						env.Subscription,
+						reason.Error.F("graph query failed: %s", execErr.Error()),
+					).Write(l); chk.E(err) {
+						return
+					}
+					return
+				}
+
+				// Send the result event
+				var res *eventenvelope.Result
+				if res, err = eventenvelope.NewResultWith(env.Subscription, resultEvent); chk.E(err) {
+					return
+				}
+				if err = res.Write(l); chk.E(err) {
+					return
+				}
+
+				// Send EOSE to signal completion
+				if err = eoseenvelope.NewFrom(env.Subscription).Write(l); chk.E(err) {
+					return
+				}
+
+				log.I.F("graph query completed for %s: method=%s, returned event kind %d",
+					l.remote, graphQuery.Method, resultEvent.Kind)
+				return
+			}
+		}
+	}
+
+	// Filter out policy config events (kind 12345) for non-policy-admin users
+	// Policy config events should only be visible to policy administrators
+	if l.policyManager != nil && l.policyManager.IsEnabled() {
+		isPolicyAdmin := l.policyManager.IsPolicyAdmin(l.authedPubkey.Load())
+		if !isPolicyAdmin {
+			// Remove kind 12345 from all filters
+			for _, f := range *env.Filters {
+				if f != nil && f.Kinds != nil && f.Kinds.Len() > 0 {
+					// Create a new kinds list without PolicyConfig
+					var filteredKinds []*kind.K
+					for _, k := range f.Kinds.K {
+						if k.K != kind.PolicyConfig.K {
+							filteredKinds = append(filteredKinds, k)
+						}
+					}
+					f.Kinds.K = filteredKinds
+				}
+			}
+		}
+	}
+
 	var events event.S
 	// Create a single context for all filter queries, isolated from the connection context
 	// to prevent query timeouts from affecting the long-lived websocket connection
@@ -115,6 +283,38 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 	)
 	defer queryCancel()
 
+	// Check cache first for single-filter queries (most common case)
+	// Multi-filter queries are not cached as they're more complex
+	if len(*env.Filters) == 1 && env.Filters != nil {
+		f := (*env.Filters)[0]
+		if cachedEvents, found := l.DB.GetCachedEvents(f); found {
+			log.D.F("REQ %s: cache HIT, sending %d cached events", env.Subscription, len(cachedEvents))
+			// Wrap cached events with current subscription ID
+			for _, ev := range cachedEvents {
+				var res *eventenvelope.Result
+				if res, err = eventenvelope.NewResultWith(env.Subscription, ev); chk.E(err) {
+					return
+				}
+				if err = res.Write(l); err != nil {
+					if !strings.Contains(err.Error(), "context canceled") {
+						chk.E(err)
+					}
+					return
+				}
+			}
+			// Send EOSE
+			if err = eoseenvelope.NewFrom(env.Subscription).Write(l); chk.E(err) {
+				return
+			}
+			// Don't create subscription for cached results with satisfied limits
+			if f.Limit != nil && len(cachedEvents) >= int(*f.Limit) {
+				log.D.F("REQ %s: limit satisfied by cache, not creating subscription", env.Subscription)
+				return
+			}
+			// Fall through to create subscription for ongoing updates
+		}
+	}
+
 	// Collect all events from all filters
 	var allEvents event.S
 	for _, f := range *env.Filters {
@@ -285,10 +485,12 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 			// Event has private tag and user is authorized - continue to privileged check
 		}
 
-		// Always filter privileged events based on kind, regardless of ACLMode
+		// Filter privileged events based on kind when ACL is active
+		// When ACL is "none", skip privileged filtering to allow open access
 		// Privileged events should only be sent to users who are authenticated and
 		// are either the event author or listed in p tags
-		if kind.IsPrivileged(ev.Kind) && accessLevel != "admin" { // admins can see all events
+		aclActive := acl.Registry.Active.Load() != "none"
+		if kind.IsPrivileged(ev.Kind) && aclActive && accessLevel != "admin" { // admins can see all events
 			log.T.C(
 				func() string {
 					return fmt.Sprintf(
@@ -297,123 +499,39 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 				},
 			)
 			pk := l.authedPubkey.Load()
-			if pk == nil {
-				// Not authenticated - cannot see privileged events
+
+			// Use centralized IsPartyInvolved function for consistent privilege checking
+			if policy.IsPartyInvolved(ev, pk) {
 				log.T.C(
 					func() string {
 						return fmt.Sprintf(
-							"privileged event %s denied - not authenticated",
-							ev.ID,
-						)
-					},
-				)
-				continue
-			}
-			// Check if user is authorized to see this privileged event
-			authorized := false
-			if utils.FastEqual(ev.Pubkey, pk) {
-				authorized = true
-				log.T.C(
-					func() string {
-						return fmt.Sprintf(
-							"privileged event %s is for logged in pubkey %0x",
+							"privileged event %s allowed for logged in pubkey %0x",
 							ev.ID, pk,
 						)
 					},
 				)
-			} else {
-				// Check p tags
-				pTags := ev.Tags.GetAll([]byte("p"))
-				for _, pTag := range pTags {
-					var pt []byte
-					if pt, err = hexenc.Dec(string(pTag.Value())); chk.E(err) {
-						continue
-					}
-					if utils.FastEqual(pt, pk) {
-						authorized = true
-						log.T.C(
-							func() string {
-								return fmt.Sprintf(
-									"privileged event %s is for logged in pubkey %0x",
-									ev.ID, pk,
-								)
-							},
-						)
-						break
-					}
-				}
-			}
-			if authorized {
 				tmp = append(tmp, ev)
 			} else {
 				log.T.C(
 					func() string {
 						return fmt.Sprintf(
-							"privileged event %s does not contain the logged in pubkey %0x",
+							"privileged event %s denied for pubkey %0x (not authenticated or not a party involved)",
 							ev.ID, pk,
 						)
 					},
 				)
 			}
 		} else {
-			// Check if policy defines this event as privileged (even if not in hardcoded list)
-			// Policy check will handle this later, but we can skip it here if not authenticated
-			// to avoid unnecessary processing
-			if l.policyManager != nil && l.policyManager.Manager != nil && l.policyManager.Manager.IsEnabled() {
-				rule, hasRule := l.policyManager.Rules[int(ev.Kind)]
-				if hasRule && rule.Privileged && accessLevel != "admin" {
-					pk := l.authedPubkey.Load()
-					if pk == nil {
-						// Not authenticated - cannot see policy-privileged events
-						log.T.C(
-							func() string {
-								return fmt.Sprintf(
-									"policy-privileged event %s denied - not authenticated",
-									ev.ID,
-								)
-							},
-						)
-						continue
-					}
-					// Policy check will verify authorization later, but we need to check
-					// if user is party to the event here
-					authorized := false
-					if utils.FastEqual(ev.Pubkey, pk) {
-						authorized = true
-					} else {
-						// Check p tags
-						pTags := ev.Tags.GetAll([]byte("p"))
-						for _, pTag := range pTags {
-							var pt []byte
-							if pt, err = hexenc.Dec(string(pTag.Value())); chk.E(err) {
-								continue
-							}
-							if utils.FastEqual(pt, pk) {
-								authorized = true
-								break
-							}
-						}
-					}
-					if !authorized {
-						log.T.C(
-							func() string {
-								return fmt.Sprintf(
-									"policy-privileged event %s does not contain the logged in pubkey %0x",
-									ev.ID, pk,
-								)
-							},
-						)
-						continue
-					}
-				}
-			}
+			// Policy-defined privileged events are handled by the policy engine
+			// at line 455+. No early filtering needed here - delegate entirely to
+			// the policy engine to avoid duplicate logic.
 			tmp = append(tmp, ev)
 		}
 	}
 	events = tmp
 
 	// Apply policy filtering for read access if policy is enabled
-	if l.policyManager != nil && l.policyManager.Manager != nil && l.policyManager.Manager.IsEnabled() {
+	if l.policyManager.IsEnabled() {
 		var policyFilteredEvents event.S
 		for _, ev := range events {
 			allowed, policyErr := l.policyManager.CheckPolicy("read", ev, l.authedPubkey.Load(), l.remote)
@@ -523,6 +641,9 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 	events = privateFilteredEvents
 
 	seen := make(map[string]struct{})
+	// Cache events for single-filter queries (without subscription ID)
+	shouldCache := len(*env.Filters) == 1 && len(events) > 0
+
 	for _, ev := range events {
 		log.T.C(
 			func() string {
@@ -543,6 +664,7 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 		); chk.E(err) {
 			return
 		}
+
 		if err = res.Write(l); err != nil {
 			// Don't log context canceled errors as they're expected during shutdown
 			if !strings.Contains(err.Error(), "context canceled") {
@@ -553,6 +675,14 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 		// track the IDs we've sent (use hex encoding for stable key)
 		seen[hexenc.Enc(ev.ID)] = struct{}{}
 	}
+
+	// Populate cache after successfully sending all events
+	// Cache the events themselves (not marshaled JSON with subscription ID)
+	if shouldCache && len(events) > 0 {
+		f := (*env.Filters)[0]
+		l.DB.CacheEvents(f, events)
+		log.D.F("REQ %s: cached %d events", env.Subscription, len(events))
+	}
 	// write the EOSE to signal to the client that all events found have been
 	// sent.
 	log.T.F("sending EOSE to %s", l.remote)
@@ -626,6 +756,8 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 		l.subscriptionsMu.Unlock()
 
 		// Register subscription with publisher
+		// Set AuthRequired based on ACL mode - when ACL is "none", don't require auth for privileged events
+		authRequired := acl.Registry.Active.Load() != "none"
 		l.publishers.Receive(
 			&W{
 				Conn:         l.conn,
@@ -634,6 +766,7 @@ func (l *Listener) HandleReq(msg []byte) (err error) {
 				Receiver:     receiver,
 				Filters:      &subbedFilters,
 				AuthedPubkey: l.authedPubkey.Load(),
+				AuthRequired: authRequired,
 			},
 		)
 

app/handle-websocket.go

@@ -10,10 +10,11 @@ import (
 	"github.com/gorilla/websocket"
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
-	"next.orly.dev/pkg/encoders/envelopes/authenvelope"
-	"next.orly.dev/pkg/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/authenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"next.orly.dev/pkg/cashu/token"
 	"next.orly.dev/pkg/protocol/publish"
-	"next.orly.dev/pkg/utils/units"
+	"git.mleku.dev/mleku/nostr/utils/units"
 )
 
 const (
@@ -21,7 +22,10 @@ const (
 	DefaultPongWait       = 60 * time.Second
 	DefaultPingWait       = DefaultPongWait / 2
 	DefaultWriteTimeout   = 3 * time.Second
-	DefaultMaxMessageSize = 512000 // Match khatru's MaxMessageSize
+	// DefaultMaxMessageSize is the maximum message size for WebSocket connections
+	// Increased from 512KB to 10MB to support large kind 3 follow lists (10k+ follows)
+	// and other large events without truncation
+	DefaultMaxMessageSize = 10 * 1024 * 1024 // 10MB
 	// ClientMessageSizeLimit is the maximum message size that clients can handle
 	// This is set to 100MB to allow large messages
 	ClientMessageSizeLimit = 100 * 1024 * 1024 // 100MB
@@ -52,6 +56,12 @@ func (s *Server) HandleWebsocket(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 whitelist:
+	// Extract and verify Cashu access token if verifier is configured
+	var cashuToken *token.Token
+	if s.CashuVerifier != nil {
+		cashuToken = s.extractWebSocketToken(r, remote)
+	}
+
 	// Create an independent context for this connection
 	// This context will be cancelled when the connection closes or server shuts down
 	ctx, cancel := context.WithCancel(s.Ctx)
@@ -83,6 +93,12 @@ whitelist:
 	})
 
 	defer conn.Close()
+	// Determine handler semaphore size from config
+	handlerSemSize := s.Config.MaxHandlersPerConnection
+	if handlerSemSize <= 0 {
+		handlerSemSize = 100 // Default if not configured
+	}
+
 	listener := &Listener{
 		ctx:            ctx,
 		cancel:         cancel,
@@ -90,11 +106,13 @@ whitelist:
 		conn:           conn,
 		remote:         remote,
 		req:            r,
+		cashuToken:     cashuToken, // Verified Cashu access token (nil if none provided)
 		startTime:      time.Now(),
 		writeChan:      make(chan publish.WriteRequest, 100), // Buffered channel for writes
 		writeDone:      make(chan struct{}),
 		messageQueue:   make(chan messageRequest, 100), // Buffered channel for message processing
 		processingDone: make(chan struct{}),
+		handlerSem:     make(chan struct{}, handlerSemSize), // Limits concurrent handlers
 		subscriptions:  make(map[string]context.CancelFunc),
 	}
 
@@ -118,7 +136,8 @@ whitelist:
 	chal := make([]byte, 32)
 	rand.Read(chal)
 	listener.challenge.Store([]byte(hex.Enc(chal)))
-	if s.Config.ACLMode != "none" {
+	// Send AUTH challenge if ACL mode requires it, or if auth is required/required for writes
+	if s.Config.ACLMode != "none" || s.Config.AuthRequired || s.Config.AuthToWrite {
 		log.D.F("sending AUTH challenge to %s", remote)
 		if err = authenvelope.NewChallengeWith(listener.challenge.Load()).
 			Write(listener); chk.E(err) {
@@ -174,6 +193,12 @@ whitelist:
 		// Wait for message processor to finish
 		<-listener.processingDone
 
+		// Wait for all spawned message handlers to complete
+		// This is critical to prevent "send on closed channel" panics
+		log.D.F("ws->%s waiting for message handlers to complete", remote)
+		listener.handlerWg.Wait()
+		log.D.F("ws->%s all message handlers completed", remote)
+
 		// Close write channel to signal worker to exit
 		close(listener.writeChan)
 		// Wait for write worker to finish
@@ -274,3 +299,54 @@ func (s *Server) Pinger(
 		}
 	}
 }
+
+// extractWebSocketToken extracts and verifies a Cashu access token from a WebSocket upgrade request.
+// Checks query param first (for browser WebSocket clients), then headers.
+// Returns nil if no token is provided or if token verification fails.
+func (s *Server) extractWebSocketToken(r *http.Request, remote string) *token.Token {
+	// Try query param first (WebSocket clients often can't set custom headers)
+	tokenStr := r.URL.Query().Get("token")
+
+	// Try X-Cashu-Token header
+	if tokenStr == "" {
+		tokenStr = r.Header.Get("X-Cashu-Token")
+	}
+
+	// Try Authorization: Cashu scheme
+	if tokenStr == "" {
+		auth := r.Header.Get("Authorization")
+		if strings.HasPrefix(auth, "Cashu ") {
+			tokenStr = strings.TrimPrefix(auth, "Cashu ")
+		}
+	}
+
+	// No token provided - this is fine, connection proceeds without token
+	if tokenStr == "" {
+		return nil
+	}
+
+	// Parse the token
+	tok, err := token.Parse(tokenStr)
+	if err != nil {
+		log.W.F("ws %s: invalid Cashu token format: %v", remote, err)
+		return nil
+	}
+
+	// Verify token - accept both "relay" and "nip46" scopes for WebSocket connections
+	// NIP-46 connections are also WebSocket-based
+	ctx := context.Background()
+	if err := s.CashuVerifier.Verify(ctx, tok, remote); err != nil {
+		log.W.F("ws %s: Cashu token verification failed: %v", remote, err)
+		return nil
+	}
+
+	// Check scope - allow "relay" or "nip46"
+	if tok.Scope != token.ScopeRelay && tok.Scope != token.ScopeNIP46 {
+		log.W.F("ws %s: Cashu token has invalid scope %q for WebSocket", remote, tok.Scope)
+		return nil
+	}
+
+	log.D.F("ws %s: verified Cashu token with scope %q, expires %v",
+		remote, tok.Scope, tok.ExpiresAt())
+	return tok
+}

app/handle-wireguard.go

@@ -0,0 +1,514 @@
+package app
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"git.mleku.dev/mleku/nostr/encoders/bech32encoding"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/httpauth"
+	"lol.mleku.dev/chk"
+	"lol.mleku.dev/log"
+
+	"next.orly.dev/pkg/acl"
+	"next.orly.dev/pkg/database"
+)
+
+// WireGuardConfigResponse is returned by the /api/wireguard/config endpoint.
+type WireGuardConfigResponse struct {
+	ConfigText string      `json:"config_text"`
+	Interface  WGInterface `json:"interface"`
+	Peer       WGPeer      `json:"peer"`
+}
+
+// WGInterface represents the [Interface] section of a WireGuard config.
+type WGInterface struct {
+	Address    string `json:"address"`
+	PrivateKey string `json:"private_key"`
+}
+
+// WGPeer represents the [Peer] section of a WireGuard config.
+type WGPeer struct {
+	PublicKey  string `json:"public_key"`
+	Endpoint   string `json:"endpoint"`
+	AllowedIPs string `json:"allowed_ips"`
+}
+
+// BunkerURLResponse is returned by the /api/bunker/url endpoint.
+type BunkerURLResponse struct {
+	URL         string `json:"url"`
+	RelayNpub   string `json:"relay_npub"`
+	RelayPubkey string `json:"relay_pubkey"`
+	InternalIP  string `json:"internal_ip"`
+}
+
+// handleWireGuardConfig returns the user's WireGuard configuration.
+// Requires NIP-98 authentication and write+ access.
+func (s *Server) handleWireGuardConfig(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Check if WireGuard is enabled
+	if !s.Config.WGEnabled {
+		http.Error(w, "WireGuard is not enabled on this relay", http.StatusNotFound)
+		return
+	}
+
+	// Check if ACL mode supports WireGuard
+	if s.Config.ACLMode == "none" {
+		http.Error(w, "WireGuard requires ACL mode 'follows' or 'managed'", http.StatusForbidden)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		http.Error(w, "NIP-98 authentication required", http.StatusUnauthorized)
+		return
+	}
+
+	// Check user has write+ access
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
+		http.Error(w, "Write access required for WireGuard", http.StatusForbidden)
+		return
+	}
+
+	// Type assert to Badger database for WireGuard methods
+	badgerDB, ok := s.DB.(*database.D)
+	if !ok {
+		http.Error(w, "WireGuard requires Badger database backend", http.StatusInternalServerError)
+		return
+	}
+
+	// Check subnet pool is available
+	if s.subnetPool == nil {
+		http.Error(w, "WireGuard subnet pool not initialized", http.StatusInternalServerError)
+		return
+	}
+
+	// Get or create WireGuard peer for this user
+	peer, err := badgerDB.GetOrCreateWireGuardPeer(pubkey, s.subnetPool)
+	if chk.E(err) {
+		log.E.F("failed to get/create WireGuard peer: %v", err)
+		http.Error(w, "Failed to create WireGuard configuration", http.StatusInternalServerError)
+		return
+	}
+
+	// Derive subnet IPs from sequence
+	subnet := s.subnetPool.SubnetForSequence(peer.Sequence)
+	clientIP := subnet.ClientIP.String()
+	serverIP := subnet.ServerIP.String()
+
+	// Get server public key
+	serverKey, err := badgerDB.GetOrCreateWireGuardServerKey()
+	if chk.E(err) {
+		log.E.F("failed to get WireGuard server key: %v", err)
+		http.Error(w, "WireGuard server not configured", http.StatusInternalServerError)
+		return
+	}
+
+	serverPubKey, err := deriveWGPublicKey(serverKey)
+	if chk.E(err) {
+		log.E.F("failed to derive server public key: %v", err)
+		http.Error(w, "WireGuard server error", http.StatusInternalServerError)
+		return
+	}
+
+	// Build endpoint
+	endpoint := fmt.Sprintf("%s:%d", s.Config.WGEndpoint, s.Config.WGPort)
+
+	// Build response
+	resp := WireGuardConfigResponse{
+		Interface: WGInterface{
+			Address:    clientIP + "/32",
+			PrivateKey: base64.StdEncoding.EncodeToString(peer.WGPrivateKey),
+		},
+		Peer: WGPeer{
+			PublicKey:  base64.StdEncoding.EncodeToString(serverPubKey),
+			Endpoint:   endpoint,
+			AllowedIPs: serverIP + "/32", // Only route bunker traffic to this peer's server IP
+		},
+	}
+
+	// Generate config text
+	resp.ConfigText = fmt.Sprintf(`[Interface]
+Address = %s
+PrivateKey = %s
+
+[Peer]
+PublicKey = %s
+Endpoint = %s
+AllowedIPs = %s
+PersistentKeepalive = 25
+`, resp.Interface.Address, resp.Interface.PrivateKey,
+		resp.Peer.PublicKey, resp.Peer.Endpoint, resp.Peer.AllowedIPs)
+
+	// If WireGuard server is running, add the peer
+	if s.wireguardServer != nil && s.wireguardServer.IsRunning() {
+		if err := s.wireguardServer.AddPeer(pubkey, peer.WGPublicKey, clientIP); chk.E(err) {
+			log.W.F("failed to add peer to running WireGuard server: %v", err)
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// handleWireGuardRegenerate generates a new WireGuard keypair for the user.
+// Requires NIP-98 authentication and write+ access.
+func (s *Server) handleWireGuardRegenerate(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Check if WireGuard is enabled
+	if !s.Config.WGEnabled {
+		http.Error(w, "WireGuard is not enabled on this relay", http.StatusNotFound)
+		return
+	}
+
+	// Check if ACL mode supports WireGuard
+	if s.Config.ACLMode == "none" {
+		http.Error(w, "WireGuard requires ACL mode 'follows' or 'managed'", http.StatusForbidden)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		http.Error(w, "NIP-98 authentication required", http.StatusUnauthorized)
+		return
+	}
+
+	// Check user has write+ access
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
+		http.Error(w, "Write access required for WireGuard", http.StatusForbidden)
+		return
+	}
+
+	// Type assert to Badger database for WireGuard methods
+	badgerDB, ok := s.DB.(*database.D)
+	if !ok {
+		http.Error(w, "WireGuard requires Badger database backend", http.StatusInternalServerError)
+		return
+	}
+
+	// Check subnet pool is available
+	if s.subnetPool == nil {
+		http.Error(w, "WireGuard subnet pool not initialized", http.StatusInternalServerError)
+		return
+	}
+
+	// Remove old peer from running server if exists
+	oldPeer, err := badgerDB.GetWireGuardPeer(pubkey)
+	if err == nil && oldPeer != nil && s.wireguardServer != nil && s.wireguardServer.IsRunning() {
+		s.wireguardServer.RemovePeer(oldPeer.WGPublicKey)
+	}
+
+	// Regenerate keypair
+	peer, err := badgerDB.RegenerateWireGuardPeer(pubkey, s.subnetPool)
+	if chk.E(err) {
+		log.E.F("failed to regenerate WireGuard peer: %v", err)
+		http.Error(w, "Failed to regenerate WireGuard configuration", http.StatusInternalServerError)
+		return
+	}
+
+	// Derive subnet IPs from sequence (same sequence as before)
+	subnet := s.subnetPool.SubnetForSequence(peer.Sequence)
+	clientIP := subnet.ClientIP.String()
+
+	log.I.F("regenerated WireGuard keypair for user: %s", hex.Enc(pubkey[:8]))
+
+	// Return success with IP (same subnet as before)
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":      "regenerated",
+		"assigned_ip": clientIP,
+	})
+}
+
+// handleBunkerURL returns the bunker connection URL.
+// Requires NIP-98 authentication and write+ access.
+func (s *Server) handleBunkerURL(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Check if bunker is enabled
+	if !s.Config.BunkerEnabled {
+		http.Error(w, "Bunker is not enabled on this relay", http.StatusNotFound)
+		return
+	}
+
+	// Check if WireGuard is enabled (required for bunker)
+	if !s.Config.WGEnabled {
+		http.Error(w, "WireGuard is required for bunker access", http.StatusNotFound)
+		return
+	}
+
+	// Check if ACL mode supports WireGuard
+	if s.Config.ACLMode == "none" {
+		http.Error(w, "Bunker requires ACL mode 'follows' or 'managed'", http.StatusForbidden)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		http.Error(w, "NIP-98 authentication required", http.StatusUnauthorized)
+		return
+	}
+
+	// Check user has write+ access
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
+		http.Error(w, "Write access required for bunker", http.StatusForbidden)
+		return
+	}
+
+	// Type assert to Badger database for WireGuard methods
+	badgerDB, ok := s.DB.(*database.D)
+	if !ok {
+		http.Error(w, "Bunker requires Badger database backend", http.StatusInternalServerError)
+		return
+	}
+
+	// Check subnet pool is available
+	if s.subnetPool == nil {
+		http.Error(w, "WireGuard subnet pool not initialized", http.StatusInternalServerError)
+		return
+	}
+
+	// Get or create WireGuard peer to get their subnet
+	peer, err := badgerDB.GetOrCreateWireGuardPeer(pubkey, s.subnetPool)
+	if chk.E(err) {
+		log.E.F("failed to get/create WireGuard peer for bunker: %v", err)
+		http.Error(w, "Failed to get WireGuard configuration", http.StatusInternalServerError)
+		return
+	}
+
+	// Derive server IP for this peer's subnet
+	subnet := s.subnetPool.SubnetForSequence(peer.Sequence)
+	serverIP := subnet.ServerIP.String()
+
+	// Get relay identity
+	relaySecret, err := s.DB.GetOrCreateRelayIdentitySecret()
+	if chk.E(err) {
+		log.E.F("failed to get relay identity: %v", err)
+		http.Error(w, "Failed to get relay identity", http.StatusInternalServerError)
+		return
+	}
+
+	relayPubkey, err := deriveNostrPublicKey(relaySecret)
+	if chk.E(err) {
+		log.E.F("failed to derive relay public key: %v", err)
+		http.Error(w, "Failed to derive relay public key", http.StatusInternalServerError)
+		return
+	}
+
+	// Encode as npub
+	relayNpubBytes, err := bech32encoding.BinToNpub(relayPubkey)
+	relayNpub := string(relayNpubBytes)
+	if chk.E(err) {
+		relayNpub = hex.Enc(relayPubkey) // Fallback to hex
+	}
+
+	// Build bunker URL using this peer's server IP
+	// Format: bunker://<relay-pubkey-hex>?relay=ws://<server-ip>:3335
+	relayPubkeyHex := hex.Enc(relayPubkey)
+	bunkerURL := fmt.Sprintf("bunker://%s?relay=ws://%s:%d",
+		relayPubkeyHex,
+		serverIP,
+		s.Config.BunkerPort,
+	)
+
+	resp := BunkerURLResponse{
+		URL:         bunkerURL,
+		RelayNpub:   relayNpub,
+		RelayPubkey: relayPubkeyHex,
+		InternalIP:  serverIP,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// handleWireGuardStatus returns whether WireGuard/Bunker are available.
+func (s *Server) handleWireGuardStatus(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	resp := map[string]interface{}{
+		"wireguard_enabled": s.Config.WGEnabled,
+		"bunker_enabled":    s.Config.BunkerEnabled,
+		"acl_mode":          s.Config.ACLMode,
+		"available":         s.Config.WGEnabled && s.Config.ACLMode != "none",
+	}
+
+	if s.wireguardServer != nil {
+		resp["wireguard_running"] = s.wireguardServer.IsRunning()
+		resp["peer_count"] = s.wireguardServer.PeerCount()
+	}
+
+	if s.bunkerServer != nil {
+		resp["bunker_sessions"] = s.bunkerServer.SessionCount()
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// RevokedKeyResponse is the JSON response for revoked keys.
+type RevokedKeyResponse struct {
+	NostrPubkey  string `json:"nostr_pubkey"`
+	WGPublicKey  string `json:"wg_public_key"`
+	Sequence     uint32 `json:"sequence"`
+	ClientIP     string `json:"client_ip"`
+	ServerIP     string `json:"server_ip"`
+	CreatedAt    int64  `json:"created_at"`
+	RevokedAt    int64  `json:"revoked_at"`
+	AccessCount  int    `json:"access_count"`
+	LastAccessAt int64  `json:"last_access_at"`
+}
+
+// AccessLogResponse is the JSON response for access logs.
+type AccessLogResponse struct {
+	NostrPubkey string `json:"nostr_pubkey"`
+	WGPublicKey string `json:"wg_public_key"`
+	Sequence    uint32 `json:"sequence"`
+	ClientIP    string `json:"client_ip"`
+	Timestamp   int64  `json:"timestamp"`
+	RemoteAddr  string `json:"remote_addr"`
+}
+
+// handleWireGuardAudit returns the user's own revoked keys and access logs.
+// This lets users see if their old WireGuard keys are still being used,
+// which could indicate they left something on or someone copied their credentials.
+// Requires NIP-98 authentication and write+ access.
+func (s *Server) handleWireGuardAudit(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Check if WireGuard is enabled
+	if !s.Config.WGEnabled {
+		http.Error(w, "WireGuard is not enabled on this relay", http.StatusNotFound)
+		return
+	}
+
+	// Validate NIP-98 authentication
+	valid, pubkey, err := httpauth.CheckAuth(r)
+	if chk.E(err) || !valid {
+		http.Error(w, "NIP-98 authentication required", http.StatusUnauthorized)
+		return
+	}
+
+	// Check user has write+ access (same as other WireGuard endpoints)
+	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+	if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
+		http.Error(w, "Write access required", http.StatusForbidden)
+		return
+	}
+
+	// Type assert to Badger database for WireGuard methods
+	badgerDB, ok := s.DB.(*database.D)
+	if !ok {
+		http.Error(w, "WireGuard requires Badger database backend", http.StatusInternalServerError)
+		return
+	}
+
+	// Check subnet pool is available
+	if s.subnetPool == nil {
+		http.Error(w, "WireGuard subnet pool not initialized", http.StatusInternalServerError)
+		return
+	}
+
+	// Get this user's revoked keys only
+	revokedKeys, err := badgerDB.GetRevokedKeys(pubkey)
+	if chk.E(err) {
+		log.E.F("failed to get revoked keys: %v", err)
+		http.Error(w, "Failed to get revoked keys", http.StatusInternalServerError)
+		return
+	}
+
+	// Get this user's access logs only
+	accessLogs, err := badgerDB.GetAccessLogs(pubkey)
+	if chk.E(err) {
+		log.E.F("failed to get access logs: %v", err)
+		http.Error(w, "Failed to get access logs", http.StatusInternalServerError)
+		return
+	}
+
+	// Convert to response format
+	var revokedResp []RevokedKeyResponse
+	for _, key := range revokedKeys {
+		subnet := s.subnetPool.SubnetForSequence(key.Sequence)
+		revokedResp = append(revokedResp, RevokedKeyResponse{
+			NostrPubkey:  hex.Enc(key.NostrPubkey),
+			WGPublicKey:  hex.Enc(key.WGPublicKey),
+			Sequence:     key.Sequence,
+			ClientIP:     subnet.ClientIP.String(),
+			ServerIP:     subnet.ServerIP.String(),
+			CreatedAt:    key.CreatedAt,
+			RevokedAt:    key.RevokedAt,
+			AccessCount:  key.AccessCount,
+			LastAccessAt: key.LastAccessAt,
+		})
+	}
+
+	var accessResp []AccessLogResponse
+	for _, logEntry := range accessLogs {
+		subnet := s.subnetPool.SubnetForSequence(logEntry.Sequence)
+		accessResp = append(accessResp, AccessLogResponse{
+			NostrPubkey: hex.Enc(logEntry.NostrPubkey),
+			WGPublicKey: hex.Enc(logEntry.WGPublicKey),
+			Sequence:    logEntry.Sequence,
+			ClientIP:    subnet.ClientIP.String(),
+			Timestamp:   logEntry.Timestamp,
+			RemoteAddr:  logEntry.RemoteAddr,
+		})
+	}
+
+	resp := map[string]interface{}{
+		"revoked_keys": revokedResp,
+		"access_logs":  accessResp,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+// deriveWGPublicKey derives a Curve25519 public key from a private key.
+func deriveWGPublicKey(privateKey []byte) ([]byte, error) {
+	if len(privateKey) != 32 {
+		return nil, fmt.Errorf("invalid private key length: %d", len(privateKey))
+	}
+
+	// Use wireguard package
+	return derivePublicKey(privateKey)
+}
+
+// deriveNostrPublicKey derives a secp256k1 public key from a secret key.
+func deriveNostrPublicKey(secretKey []byte) ([]byte, error) {
+	if len(secretKey) != 32 {
+		return nil, fmt.Errorf("invalid secret key length: %d", len(secretKey))
+	}
+
+	// Use nostr library's key derivation
+	pk, err := deriveSecp256k1PublicKey(secretKey)
+	if err != nil {
+		return nil, err
+	}
+	return pk, nil
+}

app/handle_policy_config_test.go

@@ -0,0 +1,475 @@
+package app
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/adrg/xdg"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
+	"next.orly.dev/app/config"
+	"next.orly.dev/pkg/acl"
+	"next.orly.dev/pkg/database"
+	"next.orly.dev/pkg/policy"
+	"next.orly.dev/pkg/protocol/publish"
+)
+
+// setupPolicyTestListener creates a test listener with policy system enabled
+func setupPolicyTestListener(t *testing.T, policyAdminHex string) (*Listener, *database.D, func()) {
+	tempDir, err := os.MkdirTemp("", "policy_handler_test_*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+
+	// Use a unique app name per test to avoid conflicts
+	appName := "test-policy-" + filepath.Base(tempDir)
+
+	// Create the XDG config directory and default policy file BEFORE creating the policy manager
+	configDir := filepath.Join(xdg.ConfigHome, appName)
+	if err := os.MkdirAll(configDir, 0755); err != nil {
+		os.RemoveAll(tempDir)
+		t.Fatalf("failed to create config dir: %v", err)
+	}
+
+	// Create initial policy file with admin if provided
+	var initialPolicy []byte
+	if policyAdminHex != "" {
+		initialPolicy = []byte(`{
+			"default_policy": "allow",
+			"policy_admins": ["` + policyAdminHex + `"],
+			"policy_follow_whitelist_enabled": true
+		}`)
+	} else {
+		initialPolicy = []byte(`{"default_policy": "allow"}`)
+	}
+	policyPath := filepath.Join(configDir, "policy.json")
+	if err := os.WriteFile(policyPath, initialPolicy, 0644); err != nil {
+		os.RemoveAll(tempDir)
+		os.RemoveAll(configDir)
+		t.Fatalf("failed to write policy file: %v", err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	db, err := database.New(ctx, cancel, tempDir, "info")
+	if err != nil {
+		os.RemoveAll(tempDir)
+		os.RemoveAll(configDir)
+		t.Fatalf("failed to open database: %v", err)
+	}
+
+	cfg := &config.C{
+		PolicyEnabled: true,
+		RelayURL:      "wss://test.relay",
+		Listen:        "localhost",
+		Port:          3334,
+		ACLMode:       "none",
+		AppName:       appName,
+	}
+
+	// Create policy manager - now config file exists at XDG path
+	policyManager := policy.NewWithManager(ctx, cfg.AppName, cfg.PolicyEnabled, "")
+
+	server := &Server{
+		Ctx:             ctx,
+		Config:          cfg,
+		DB:              db,
+		publishers:      publish.New(NewPublisher(ctx)),
+		policyManager:   policyManager,
+		cfg:             cfg,
+		db:              db,
+		messagePauseMutex: sync.RWMutex{},
+	}
+
+	// Configure ACL registry
+	acl.Registry.SetMode(cfg.ACLMode)
+	if err = acl.Registry.Configure(cfg, db, ctx); err != nil {
+		db.Close()
+		os.RemoveAll(tempDir)
+		os.RemoveAll(configDir)
+		t.Fatalf("failed to configure ACL: %v", err)
+	}
+
+	listener := &Listener{
+		Server:         server,
+		ctx:            ctx,
+		writeChan:      make(chan publish.WriteRequest, 100),
+		writeDone:      make(chan struct{}),
+		messageQueue:   make(chan messageRequest, 100),
+		processingDone: make(chan struct{}),
+		subscriptions:  make(map[string]context.CancelFunc),
+	}
+
+	// Start write worker and message processor
+	go listener.writeWorker()
+	go listener.messageProcessor()
+
+	cleanup := func() {
+		close(listener.writeChan)
+		<-listener.writeDone
+		close(listener.messageQueue)
+		<-listener.processingDone
+		db.Close()
+		os.RemoveAll(tempDir)
+		os.RemoveAll(configDir)
+	}
+
+	return listener, db, cleanup
+}
+
+// createPolicyConfigEvent creates a kind 12345 policy config event
+func createPolicyConfigEvent(t *testing.T, signer *p8k.Signer, policyJSON string) *event.E {
+	ev := event.New()
+	ev.CreatedAt = time.Now().Unix()
+	ev.Kind = kind.PolicyConfig.K
+	ev.Content = []byte(policyJSON)
+	ev.Tags = tag.NewS()
+
+	if err := ev.Sign(signer); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	return ev
+}
+
+// TestHandlePolicyConfigUpdate_ValidAdmin tests policy update from valid admin
+// Policy admins can extend rules but cannot modify protected fields (owners, policy_admins)
+func TestHandlePolicyConfigUpdate_ValidAdmin(t *testing.T) {
+	// Create admin signer
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Create valid policy update event that ONLY extends, doesn't modify protected fields
+	// Note: policy_admins must stay the same (policy admins cannot change this field)
+	newPolicyJSON := `{
+		"default_policy": "allow",
+		"policy_admins": ["` + adminHex + `"],
+		"kind": {"whitelist": [1, 3, 7]}
+	}`
+
+	ev := createPolicyConfigEvent(t, adminSigner, newPolicyJSON)
+
+	// Handle the event
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err != nil {
+		t.Errorf("Expected success but got error: %v", err)
+	}
+
+	// Verify policy was updated (kind whitelist was extended)
+	// Note: default_policy should still be "allow" from original
+	if listener.policyManager.DefaultPolicy != "allow" {
+		t.Errorf("Policy was not updated correctly, default_policy = %q, expected 'allow'",
+			listener.policyManager.DefaultPolicy)
+	}
+}
+
+// TestHandlePolicyConfigUpdate_NonAdmin tests policy update rejection from non-admin
+func TestHandlePolicyConfigUpdate_NonAdmin(t *testing.T) {
+	// Create admin signer
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	// Create non-admin signer
+	nonAdminSigner := p8k.MustNew()
+	if err := nonAdminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate non-admin keypair: %v", err)
+	}
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Create policy update event from non-admin
+	newPolicyJSON := `{"default_policy": "deny"}`
+	ev := createPolicyConfigEvent(t, nonAdminSigner, newPolicyJSON)
+
+	// Handle the event - should be rejected
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err == nil {
+		t.Error("Expected error for non-admin update but got none")
+	}
+
+	// Verify policy was NOT updated
+	if listener.policyManager.DefaultPolicy != "allow" {
+		t.Error("Policy should not have been updated by non-admin")
+	}
+}
+
+// TestHandlePolicyConfigUpdate_InvalidJSON tests rejection of invalid JSON
+func TestHandlePolicyConfigUpdate_InvalidJSON(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Create event with invalid JSON
+	ev := createPolicyConfigEvent(t, adminSigner, `{"invalid json`)
+
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err == nil {
+		t.Error("Expected error for invalid JSON but got none")
+	}
+
+	// Policy should remain unchanged
+	if listener.policyManager.DefaultPolicy != "allow" {
+		t.Error("Policy should not have been updated with invalid JSON")
+	}
+}
+
+// TestHandlePolicyConfigUpdate_InvalidPubkey tests rejection of invalid admin pubkeys
+func TestHandlePolicyConfigUpdate_InvalidPubkey(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Try to update with invalid admin pubkey
+	invalidPolicyJSON := `{
+		"default_policy": "deny",
+		"policy_admins": ["not-a-valid-pubkey"]
+	}`
+	ev := createPolicyConfigEvent(t, adminSigner, invalidPolicyJSON)
+
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err == nil {
+		t.Error("Expected error for invalid admin pubkey but got none")
+	}
+
+	// Policy should remain unchanged
+	if listener.policyManager.DefaultPolicy != "allow" {
+		t.Error("Policy should not have been updated with invalid admin pubkey")
+	}
+}
+
+// TestHandlePolicyConfigUpdate_PolicyAdminCannotModifyProtectedFields tests that policy admins
+// cannot modify the owners or policy_admins fields (these are protected, owner-only fields)
+func TestHandlePolicyConfigUpdate_PolicyAdminCannotModifyProtectedFields(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	// Create second admin
+	admin2Hex := "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Try to add second admin (policy_admins is a protected field)
+	newPolicyJSON := `{
+		"default_policy": "allow",
+		"policy_admins": ["` + adminHex + `", "` + admin2Hex + `"]
+	}`
+	ev := createPolicyConfigEvent(t, adminSigner, newPolicyJSON)
+
+	// This should FAIL because policy admins cannot modify the policy_admins field
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err == nil {
+		t.Error("Expected error when policy admin tries to modify policy_admins (protected field)")
+	}
+
+	// Second admin should NOT be in the list since update was rejected
+	admin2Bin, _ := hex.Dec(admin2Hex)
+	if listener.policyManager.IsPolicyAdmin(admin2Bin) {
+		t.Error("Second admin should NOT have been added - policy_admins is protected")
+	}
+}
+
+// TestHandlePolicyAdminFollowListUpdate tests follow list update from admin
+func TestHandlePolicyAdminFollowListUpdate(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	listener, db, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Create a kind 3 follow list event from admin
+	ev := event.New()
+	ev.CreatedAt = time.Now().Unix()
+	ev.Kind = kind.FollowList.K
+	ev.Content = []byte("")
+	ev.Tags = tag.NewS()
+
+	// Add some follows
+	follow1Hex := "1111111111111111111111111111111111111111111111111111111111111111"
+	follow2Hex := "2222222222222222222222222222222222222222222222222222222222222222"
+	ev.Tags.Append(tag.NewFromAny("p", follow1Hex))
+	ev.Tags.Append(tag.NewFromAny("p", follow2Hex))
+
+	if err := ev.Sign(adminSigner); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	// Save the event to database first
+	if _, err := db.SaveEvent(listener.ctx, ev); err != nil {
+		t.Fatalf("Failed to save follow list event: %v", err)
+	}
+
+	// Handle the follow list update
+	err := listener.HandlePolicyAdminFollowListUpdate(ev)
+	if err != nil {
+		t.Errorf("Expected success but got error: %v", err)
+	}
+
+	// Verify follows were added
+	follow1Bin, _ := hex.Dec(follow1Hex)
+	follow2Bin, _ := hex.Dec(follow2Hex)
+
+	if !listener.policyManager.IsPolicyFollow(follow1Bin) {
+		t.Error("Follow 1 should have been added to policy follows")
+	}
+	if !listener.policyManager.IsPolicyFollow(follow2Bin) {
+		t.Error("Follow 2 should have been added to policy follows")
+	}
+}
+
+// TestIsPolicyAdminFollowListEvent tests detection of admin follow list events
+func TestIsPolicyAdminFollowListEvent(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	nonAdminSigner := p8k.MustNew()
+	if err := nonAdminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate non-admin keypair: %v", err)
+	}
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Test admin's kind 3 event
+	adminFollowEv := event.New()
+	adminFollowEv.Kind = kind.FollowList.K
+	adminFollowEv.Tags = tag.NewS()
+	if err := adminFollowEv.Sign(adminSigner); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	if !listener.IsPolicyAdminFollowListEvent(adminFollowEv) {
+		t.Error("Should detect admin's follow list event")
+	}
+
+	// Test non-admin's kind 3 event
+	nonAdminFollowEv := event.New()
+	nonAdminFollowEv.Kind = kind.FollowList.K
+	nonAdminFollowEv.Tags = tag.NewS()
+	if err := nonAdminFollowEv.Sign(nonAdminSigner); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	if listener.IsPolicyAdminFollowListEvent(nonAdminFollowEv) {
+		t.Error("Should not detect non-admin's follow list event")
+	}
+
+	// Test admin's non-kind-3 event
+	adminOtherEv := event.New()
+	adminOtherEv.Kind = 1 // Kind 1, not follow list
+	adminOtherEv.Tags = tag.NewS()
+	if err := adminOtherEv.Sign(adminSigner); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	if listener.IsPolicyAdminFollowListEvent(adminOtherEv) {
+		t.Error("Should not detect admin's non-follow-list event")
+	}
+}
+
+// TestIsPolicyConfigEvent tests detection of policy config events
+func TestIsPolicyConfigEvent(t *testing.T) {
+	signer := p8k.MustNew()
+	if err := signer.Generate(); err != nil {
+		t.Fatalf("Failed to generate keypair: %v", err)
+	}
+
+	// Kind 12345 event
+	policyEv := event.New()
+	policyEv.Kind = kind.PolicyConfig.K
+	policyEv.Tags = tag.NewS()
+	if err := policyEv.Sign(signer); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	if !IsPolicyConfigEvent(policyEv) {
+		t.Error("Should detect kind 12345 as policy config event")
+	}
+
+	// Non-policy event
+	otherEv := event.New()
+	otherEv.Kind = 1
+	otherEv.Tags = tag.NewS()
+	if err := otherEv.Sign(signer); err != nil {
+		t.Fatalf("Failed to sign event: %v", err)
+	}
+
+	if IsPolicyConfigEvent(otherEv) {
+		t.Error("Should not detect kind 1 as policy config event")
+	}
+}
+
+// TestMessageProcessingPauseDuringPolicyUpdate tests that message processing is paused
+func TestMessageProcessingPauseDuringPolicyUpdate(t *testing.T) {
+	adminSigner := p8k.MustNew()
+	if err := adminSigner.Generate(); err != nil {
+		t.Fatalf("Failed to generate admin keypair: %v", err)
+	}
+	adminHex := hex.Enc(adminSigner.Pub())
+
+	listener, _, cleanup := setupPolicyTestListener(t, adminHex)
+	defer cleanup()
+
+	// Track if pause was called
+	pauseCalled := false
+	resumeCalled := false
+
+	// We can't easily mock the mutex, but we can verify the policy update succeeds
+	// which implies the pause/resume cycle completed
+	// Note: policy_admins must stay the same (protected field)
+	newPolicyJSON := `{
+		"default_policy": "allow",
+		"policy_admins": ["` + adminHex + `"],
+		"kind": {"whitelist": [1, 3, 5, 7]}
+	}`
+	ev := createPolicyConfigEvent(t, adminSigner, newPolicyJSON)
+
+	err := listener.HandlePolicyConfigUpdate(ev)
+	if err != nil {
+		t.Errorf("Policy update failed: %v", err)
+	}
+
+	// If we got here without deadlock, the pause/resume worked
+	_ = pauseCalled
+	_ = resumeCalled
+
+	// Verify policy was actually updated (kind whitelist was extended)
+	if listener.policyManager.DefaultPolicy != "allow" {
+		t.Error("Policy should have been updated")
+	}
+}

app/listener.go

@@ -1,6 +1,7 @@
 package app
 
 import (
+	"bytes"
 	"context"
 	"net/http"
 	"strings"
@@ -12,9 +13,10 @@ import (
 	"lol.mleku.dev/errorf"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
+	"next.orly.dev/pkg/cashu/token"
 	"next.orly.dev/pkg/database"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/filter"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
 	"next.orly.dev/pkg/protocol/publish"
 	"next.orly.dev/pkg/utils"
 	atomicutils "next.orly.dev/pkg/utils/atomic"
@@ -29,6 +31,7 @@ type Listener struct {
 	req              *http.Request
 	challenge        atomicutils.Bytes
 	authedPubkey     atomicutils.Bytes
+	cashuToken       *token.Token // Verified Cashu access token for this connection (nil if no token)
 	startTime        time.Time
 	isBlacklisted    bool      // Marker to identify blacklisted IPs
 	blacklistTimeout time.Time // When to timeout blacklisted connections
@@ -37,6 +40,9 @@ type Listener struct {
 	// Message processing queue for async handling
 	messageQueue     chan messageRequest // Buffered channel for message processing
 	processingDone   chan struct{}       // Closed when message processor exits
+	handlerWg        sync.WaitGroup      // Tracks spawned message handler goroutines
+	handlerSem       chan struct{}       // Limits concurrent message handlers per connection
+	authProcessing   sync.RWMutex        // Ensures AUTH completes before other messages check authentication
 	// Flow control counters (atomic for concurrent access)
 	droppedMessages  atomic.Int64 // Messages dropped due to full queue
 	// Diagnostics: per-connection counters
@@ -85,6 +91,15 @@ func (l *Listener) QueueMessage(data []byte, remote string) bool {
 
 
 func (l *Listener) Write(p []byte) (n int, err error) {
+	// Defensive: recover from any panic when sending to closed channel
+	defer func() {
+		if r := recover(); r != nil {
+			log.D.F("ws->%s write panic recovered (channel likely closed): %v", l.remote, r)
+			err = errorf.E("write channel closed")
+			n = 0
+		}
+	}()
+
 	// Send write request to channel - non-blocking with timeout
 	select {
 	case <-l.ctx.Done():
@@ -99,6 +114,14 @@ func (l *Listener) Write(p []byte) (n int, err error) {
 
 // WriteControl sends a control message through the write channel
 func (l *Listener) WriteControl(messageType int, data []byte, deadline time.Time) (err error) {
+	// Defensive: recover from any panic when sending to closed channel
+	defer func() {
+		if r := recover(); r != nil {
+			log.D.F("ws->%s writeControl panic recovered (channel likely closed): %v", l.remote, r)
+			err = errorf.E("write channel closed")
+		}
+	}()
+
 	select {
 	case <-l.ctx.Done():
 		return l.ctx.Err()
@@ -143,6 +166,12 @@ func (l *Listener) writeWorker() {
 				return
 			}
 
+			// Skip writes if no connection (unit tests)
+			if l.conn == nil {
+				log.T.F("ws->%s skipping write (no connection)", l.remote)
+				continue
+			}
+
 			// Handle the write request
 			var err error
 			if req.IsPing {
@@ -194,9 +223,43 @@ func (l *Listener) messageProcessor() {
 				return
 			}
 
-			// Process the message in a separate goroutine to avoid blocking
-			// This allows multiple messages to be processed concurrently (like khatru does)
-			go l.HandleMessage(req.data, req.remote)
+			// Lock immediately to ensure AUTH is processed before subsequent messages
+			// are dequeued. This prevents race conditions where EVENT checks authentication
+			// before AUTH completes.
+			l.authProcessing.Lock()
+
+			// Check if this is an AUTH message by looking for the ["AUTH" prefix
+			isAuthMessage := len(req.data) > 7 && bytes.HasPrefix(req.data, []byte(`["AUTH"`))
+
+			if isAuthMessage {
+				// Process AUTH message synchronously while holding lock
+				// This blocks the messageProcessor from dequeuing the next message
+				// until authentication is complete and authedPubkey is set
+				log.D.F("ws->%s processing AUTH synchronously with lock", req.remote)
+				l.HandleMessage(req.data, req.remote)
+				// Unlock after AUTH completes so subsequent messages see updated authedPubkey
+				l.authProcessing.Unlock()
+			} else {
+				// Not AUTH - unlock immediately and process concurrently
+				// The next message can now be dequeued (possibly another non-AUTH to process concurrently)
+				l.authProcessing.Unlock()
+
+				// Acquire semaphore to limit concurrent handlers (blocking with context awareness)
+				select {
+				case l.handlerSem <- struct{}{}:
+					// Semaphore acquired
+				case <-l.ctx.Done():
+					return
+				}
+				l.handlerWg.Add(1)
+				go func(data []byte, remote string) {
+					defer func() {
+						<-l.handlerSem // Release semaphore
+						l.handlerWg.Done()
+					}()
+					l.HandleMessage(data, remote)
+				}(req.data, req.remote)
+			}
 		}
 	}
 }
@@ -216,12 +279,12 @@ func (l *Listener) getManagedACL() *database.ManagedACL {
 
 // QueryEvents queries events using the database QueryEvents method
 func (l *Listener) QueryEvents(ctx context.Context, f *filter.F) (event.S, error) {
-	return l.D.QueryEvents(ctx, f)
+	return l.DB.QueryEvents(ctx, f)
 }
 
 // QueryAllVersions queries events using the database QueryAllVersions method
 func (l *Listener) QueryAllVersions(ctx context.Context, f *filter.F) (event.S, error) {
-	return l.D.QueryAllVersions(ctx, f)
+	return l.DB.QueryAllVersions(ctx, f)
 }
 
 // canSeePrivateEvent checks if the authenticated user can see an event with a private tag

app/main.go

@@ -14,17 +14,25 @@ import (
 	"lol.mleku.dev/log"
 	"next.orly.dev/app/config"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/crypto/keys"
+	"git.mleku.dev/mleku/nostr/crypto/keys"
 	"next.orly.dev/pkg/database"
-	"next.orly.dev/pkg/encoders/bech32encoding"
+	"git.mleku.dev/mleku/nostr/encoders/bech32encoding"
+	"next.orly.dev/pkg/neo4j"
 	"next.orly.dev/pkg/policy"
+	"next.orly.dev/pkg/protocol/graph"
+	"next.orly.dev/pkg/protocol/nip43"
 	"next.orly.dev/pkg/protocol/publish"
+	"next.orly.dev/pkg/bunker"
+	"next.orly.dev/pkg/ratelimit"
 	"next.orly.dev/pkg/spider"
 	dsync "next.orly.dev/pkg/sync"
+	"next.orly.dev/pkg/wireguard"
+
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
 )
 
 func Run(
-	ctx context.Context, cfg *config.C, db *database.D,
+	ctx context.Context, cfg *config.C, db database.Database, limiter *ratelimit.Limiter,
 ) (quit chan struct{}) {
 	quit = make(chan struct{})
 	var once sync.Once
@@ -62,23 +70,101 @@ func Run(
 	}
 	// start listener
 	l := &Server{
-		Ctx:        ctx,
-		Config:     cfg,
-		D:          db,
-		publishers: publish.New(NewPublisher(ctx)),
-		Admins:     adminKeys,
-		Owners:     ownerKeys,
+		Ctx:         ctx,
+		Config:      cfg,
+		DB:          db,
+		publishers:  publish.New(NewPublisher(ctx)),
+		Admins:      adminKeys,
+		Owners:      ownerKeys,
+		rateLimiter: limiter,
+		cfg:         cfg,
+		db:          db,
+	}
+
+	// Initialize NIP-43 invite manager if enabled
+	if cfg.NIP43Enabled {
+		l.InviteManager = nip43.NewInviteManager(cfg.NIP43InviteExpiry)
+		log.I.F("NIP-43 invite system enabled with %v expiry", cfg.NIP43InviteExpiry)
 	}
 
 	// Initialize sprocket manager
 	l.sprocketManager = NewSprocketManager(ctx, cfg.AppName, cfg.SprocketEnabled)
 
 	// Initialize policy manager
-	l.policyManager = policy.NewWithManager(ctx, cfg.AppName, cfg.PolicyEnabled)
+	l.policyManager = policy.NewWithManager(ctx, cfg.AppName, cfg.PolicyEnabled, cfg.PolicyPath)
 
-	// Initialize spider manager based on mode
-	if cfg.SpiderMode != "none" {
-		if l.spiderManager, err = spider.New(ctx, db, l.publishers, cfg.SpiderMode); chk.E(err) {
+	// Merge policy-defined owners with environment-defined owners
+	// This allows cloud deployments to add owners via policy.json when env vars cannot be modified
+	if l.policyManager != nil {
+		policyOwners := l.policyManager.GetOwnersBin()
+		if len(policyOwners) > 0 {
+			// Deduplicate when merging
+			existingOwners := make(map[string]struct{})
+			for _, owner := range l.Owners {
+				existingOwners[string(owner)] = struct{}{}
+			}
+			for _, policyOwner := range policyOwners {
+				if _, exists := existingOwners[string(policyOwner)]; !exists {
+					l.Owners = append(l.Owners, policyOwner)
+					existingOwners[string(policyOwner)] = struct{}{}
+				}
+			}
+			log.I.F("merged %d policy-defined owners with %d environment-defined owners (total: %d unique owners)",
+				len(policyOwners), len(ownerKeys), len(l.Owners))
+		}
+	}
+
+	// Initialize policy follows from database (load follow lists of policy admins)
+	// This must be done after policy manager initialization but before accepting connections
+	if err := l.InitializePolicyFollows(); err != nil {
+		log.W.F("failed to initialize policy follows: %v", err)
+		// Continue anyway - follows can be loaded when admins update their follow lists
+	}
+
+	// Cleanup any kind 3 events that lost their p tags (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		if err := badgerDB.CleanupKind3WithoutPTags(ctx); chk.E(err) {
+			log.E.F("failed to cleanup kind 3 events: %v", err)
+		}
+	}
+
+	// Initialize graph query executor (Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		// Get relay identity key for signing graph query responses
+		relaySecretKey, err := badgerDB.GetOrCreateRelayIdentitySecret()
+		if err != nil {
+			log.E.F("failed to get relay identity key for graph executor: %v", err)
+		} else {
+			// Create the graph adapter and executor
+			graphAdapter := database.NewGraphAdapter(badgerDB)
+			if l.graphExecutor, err = graph.NewExecutor(graphAdapter, relaySecretKey); err != nil {
+				log.E.F("failed to create graph executor: %v", err)
+			} else {
+				log.I.F("graph query executor initialized (Badger backend)")
+			}
+		}
+	}
+
+	// Initialize graph query executor (Neo4j backend)
+	if neo4jDB, ok := db.(*neo4j.N); ok {
+		// Get relay identity key for signing graph query responses
+		relaySecretKey, err := neo4jDB.GetOrCreateRelayIdentitySecret()
+		if err != nil {
+			log.E.F("failed to get relay identity key for graph executor: %v", err)
+		} else {
+			// Create the graph adapter and executor
+			graphAdapter := neo4j.NewGraphAdapter(neo4jDB)
+			if l.graphExecutor, err = graph.NewExecutor(graphAdapter, relaySecretKey); err != nil {
+				log.E.F("failed to create graph executor: %v", err)
+			} else {
+				log.I.F("graph query executor initialized (Neo4j backend)")
+			}
+		}
+	}
+
+	// Initialize spider manager based on mode (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok && cfg.SpiderMode != "none" {
+		if l.spiderManager, err = spider.New(ctx, badgerDB, l.publishers, cfg.SpiderMode); chk.E(err) {
 			log.E.F("failed to create spider manager: %v", err)
 		} else {
 			// Set up callbacks for follows mode
@@ -113,73 +199,242 @@ func Run(
 				log.E.F("failed to start spider manager: %v", err)
 			} else {
 				log.I.F("spider manager started successfully in '%s' mode", cfg.SpiderMode)
-			}
-		}
-	}
 
-	// Initialize relay group manager
-	l.relayGroupMgr = dsync.NewRelayGroupManager(db, cfg.RelayGroupAdmins)
-
-	// Initialize sync manager if relay peers are configured
-	var peers []string
-	if len(cfg.RelayPeers) > 0 {
-		peers = cfg.RelayPeers
-	} else {
-		// Try to get peers from relay group configuration
-		if config, err := l.relayGroupMgr.FindAuthoritativeConfig(ctx); err == nil && config != nil {
-			peers = config.Relays
-			log.I.F("using relay group configuration with %d peers", len(peers))
-		}
-	}
-
-	if len(peers) > 0 {
-		// Get relay identity for node ID
-		sk, err := db.GetOrCreateRelayIdentitySecret()
-		if err != nil {
-			log.E.F("failed to get relay identity for sync: %v", err)
-		} else {
-			nodeID, err := keys.SecretBytesToPubKeyHex(sk)
-			if err != nil {
-				log.E.F("failed to derive pubkey for sync node ID: %v", err)
-			} else {
-				relayURL := cfg.RelayURL
-				if relayURL == "" {
-					relayURL = fmt.Sprintf("http://localhost:%d", cfg.Port)
+				// Hook up follow list update notifications from ACL to spider
+				if cfg.SpiderMode == "follows" {
+					for _, aclInstance := range acl.Registry.ACL {
+						if aclInstance.Type() == "follows" {
+							if follows, ok := aclInstance.(*acl.Follows); ok {
+								follows.SetFollowListUpdateCallback(func() {
+									log.I.F("follow list updated, notifying spider")
+									l.spiderManager.NotifyFollowListUpdate()
+								})
+								log.I.F("spider: follow list update notifications configured")
+							}
+						}
+					}
 				}
-				l.syncManager = dsync.NewManager(ctx, db, nodeID, relayURL, peers, l.relayGroupMgr, l.policyManager)
-				log.I.F("distributed sync manager initialized with %d peers", len(peers))
 			}
 		}
 	}
 
-	// Initialize cluster manager for cluster replication
-	var clusterAdminNpubs []string
-	if len(cfg.ClusterAdmins) > 0 {
-		clusterAdminNpubs = cfg.ClusterAdmins
-	} else {
-		// Default to regular admins if no cluster admins specified
-		for _, admin := range cfg.Admins {
-			clusterAdminNpubs = append(clusterAdminNpubs, admin)
+	// Initialize directory spider if enabled (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok && cfg.DirectorySpiderEnabled {
+		if l.directorySpider, err = spider.NewDirectorySpider(
+			ctx,
+			badgerDB,
+			l.publishers,
+			cfg.DirectorySpiderInterval,
+			cfg.DirectorySpiderMaxHops,
+		); chk.E(err) {
+			log.E.F("failed to create directory spider: %v", err)
+		} else {
+			// Set up callback to get seed pubkeys (whitelisted users)
+			l.directorySpider.SetSeedCallback(func() [][]byte {
+				var pubkeys [][]byte
+				// Get followed pubkeys from follows ACL if available
+				for _, aclInstance := range acl.Registry.ACL {
+					if aclInstance.Type() == "follows" {
+						if follows, ok := aclInstance.(*acl.Follows); ok {
+							pubkeys = append(pubkeys, follows.GetFollowedPubkeys()...)
+						}
+					}
+				}
+				// Fall back to admin keys if no follows ACL
+				if len(pubkeys) == 0 {
+					pubkeys = adminKeys
+				}
+				return pubkeys
+			})
+
+			if err = l.directorySpider.Start(); chk.E(err) {
+				log.E.F("failed to start directory spider: %v", err)
+			} else {
+				log.I.F("directory spider started (interval: %v, max hops: %d)",
+					cfg.DirectorySpiderInterval, cfg.DirectorySpiderMaxHops)
+			}
 		}
 	}
 
-	if len(clusterAdminNpubs) > 0 {
-		l.clusterManager = dsync.NewClusterManager(ctx, db, clusterAdminNpubs, cfg.ClusterPropagatePrivilegedEvents, l.publishers)
-		l.clusterManager.Start()
-		log.I.F("cluster replication manager initialized with %d admin npubs", len(clusterAdminNpubs))
+	// Initialize relay group manager (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		l.relayGroupMgr = dsync.NewRelayGroupManager(badgerDB, cfg.RelayGroupAdmins)
+	} else if cfg.SpiderMode != "none" || len(cfg.RelayPeers) > 0 || len(cfg.ClusterAdmins) > 0 {
+		log.I.Ln("spider, sync, and cluster features require Badger backend (currently using alternative backend)")
 	}
 
-	// Initialize the user interface
+	// Initialize sync manager if relay peers are configured (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		var peers []string
+		if len(cfg.RelayPeers) > 0 {
+			peers = cfg.RelayPeers
+		} else {
+			// Try to get peers from relay group configuration
+			if l.relayGroupMgr != nil {
+				if config, err := l.relayGroupMgr.FindAuthoritativeConfig(ctx); err == nil && config != nil {
+					peers = config.Relays
+					log.I.F("using relay group configuration with %d peers", len(peers))
+				}
+			}
+		}
+
+		if len(peers) > 0 {
+			// Get relay identity for node ID
+			sk, err := db.GetOrCreateRelayIdentitySecret()
+			if err != nil {
+				log.E.F("failed to get relay identity for sync: %v", err)
+			} else {
+				nodeID, err := keys.SecretBytesToPubKeyHex(sk)
+				if err != nil {
+					log.E.F("failed to derive pubkey for sync node ID: %v", err)
+				} else {
+					relayURL := cfg.RelayURL
+					if relayURL == "" {
+						relayURL = fmt.Sprintf("http://localhost:%d", cfg.Port)
+					}
+					l.syncManager = dsync.NewManager(ctx, badgerDB, nodeID, relayURL, peers, l.relayGroupMgr, l.policyManager)
+					log.I.F("distributed sync manager initialized with %d peers", len(peers))
+				}
+			}
+		}
+	}
+
+	// Initialize cluster manager for cluster replication (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		var clusterAdminNpubs []string
+		if len(cfg.ClusterAdmins) > 0 {
+			clusterAdminNpubs = cfg.ClusterAdmins
+		} else {
+			// Default to regular admins if no cluster admins specified
+			for _, admin := range cfg.Admins {
+				clusterAdminNpubs = append(clusterAdminNpubs, admin)
+			}
+		}
+
+		if len(clusterAdminNpubs) > 0 {
+			l.clusterManager = dsync.NewClusterManager(ctx, badgerDB, clusterAdminNpubs, cfg.ClusterPropagatePrivilegedEvents, l.publishers)
+			l.clusterManager.Start()
+			log.I.F("cluster replication manager initialized with %d admin npubs", len(clusterAdminNpubs))
+		}
+	}
+
+	// Initialize Blossom blob storage server (only for Badger backend)
+	// MUST be done before UserInterface() which registers routes
+	if badgerDB, ok := db.(*database.D); ok {
+		log.I.F("Badger backend detected, initializing Blossom server...")
+		if l.blossomServer, err = initializeBlossomServer(ctx, cfg, badgerDB); err != nil {
+			log.E.F("failed to initialize blossom server: %v", err)
+			// Continue without blossom server
+		} else if l.blossomServer != nil {
+			log.I.F("blossom blob storage server initialized")
+		} else {
+			log.W.F("blossom server initialization returned nil without error")
+		}
+	} else {
+		log.I.F("Non-Badger backend detected (type: %T), Blossom server not available", db)
+	}
+
+	// Initialize WireGuard VPN and NIP-46 Bunker (only for Badger backend)
+	// Requires ACL mode 'follows' or 'managed' - no point for open relays
+	if badgerDB, ok := db.(*database.D); ok && cfg.WGEnabled && cfg.ACLMode != "none" {
+		if cfg.WGEndpoint == "" {
+			log.E.F("WireGuard enabled but ORLY_WG_ENDPOINT not set - skipping")
+		} else {
+			// Get or create the subnet pool (restores seed and allocations from DB)
+			subnetPool, err := badgerDB.GetOrCreateSubnetPool(cfg.WGNetwork)
+			if err != nil {
+				log.E.F("failed to create subnet pool: %v", err)
+			} else {
+				l.subnetPool = subnetPool
+
+				// Get or create WireGuard server key
+				wgServerKey, err := badgerDB.GetOrCreateWireGuardServerKey()
+				if err != nil {
+					log.E.F("failed to get WireGuard server key: %v", err)
+				} else {
+					// Create WireGuard server
+					wgConfig := &wireguard.Config{
+						Port:       cfg.WGPort,
+						Endpoint:   cfg.WGEndpoint,
+						PrivateKey: wgServerKey,
+						Network:    cfg.WGNetwork,
+						ServerIP:   "10.73.0.1",
+					}
+
+					l.wireguardServer, err = wireguard.New(wgConfig)
+					if err != nil {
+						log.E.F("failed to create WireGuard server: %v", err)
+					} else {
+						if err = l.wireguardServer.Start(); err != nil {
+							log.E.F("failed to start WireGuard server: %v", err)
+						} else {
+							log.I.F("WireGuard VPN server started on UDP port %d", cfg.WGPort)
+
+							// Load existing peers from database and add to server
+							peers, err := badgerDB.GetAllWireGuardPeers()
+							if err != nil {
+								log.W.F("failed to load existing WireGuard peers: %v", err)
+							} else {
+								for _, peer := range peers {
+									// Derive client IP from sequence
+									subnet := subnetPool.SubnetForSequence(peer.Sequence)
+									clientIP := subnet.ClientIP.String()
+									if err := l.wireguardServer.AddPeer(peer.NostrPubkey, peer.WGPublicKey, clientIP); err != nil {
+										log.W.F("failed to add existing peer: %v", err)
+									}
+								}
+								if len(peers) > 0 {
+									log.I.F("loaded %d existing WireGuard peers", len(peers))
+								}
+							}
+
+						// Initialize bunker if enabled
+						if cfg.BunkerEnabled {
+							// Get relay identity for signing
+							relaySecretKey, err := badgerDB.GetOrCreateRelayIdentitySecret()
+							if err != nil {
+								log.E.F("failed to get relay identity for bunker: %v", err)
+							} else {
+								// Create signer from secret key
+								relaySigner, sigErr := p8k.New()
+								if sigErr != nil {
+									log.E.F("failed to create signer for bunker: %v", sigErr)
+								} else if sigErr = relaySigner.InitSec(relaySecretKey); sigErr != nil {
+									log.E.F("failed to init signer for bunker: %v", sigErr)
+								} else {
+								relayPubkey := relaySigner.Pub()
+
+								bunkerConfig := &bunker.Config{
+									RelaySigner: relaySigner,
+									RelayPubkey: relayPubkey[:],
+									Netstack:    l.wireguardServer.GetNetstack(),
+									ListenAddr:  fmt.Sprintf("10.73.0.1:%d", cfg.BunkerPort),
+								}
+
+								l.bunkerServer = bunker.New(bunkerConfig)
+								if err = l.bunkerServer.Start(); err != nil {
+									log.E.F("failed to start bunker server: %v", err)
+								} else {
+									log.I.F("NIP-46 bunker server started on 10.73.0.1:%d (WireGuard only)", cfg.BunkerPort)
+								}
+								}
+							}
+						}
+						}
+					}
+				}
+			}
+		}
+	} else if cfg.WGEnabled && cfg.ACLMode == "none" {
+		log.I.F("WireGuard disabled: requires ACL mode 'follows' or 'managed' (currently: 'none')")
+	}
+
+	// Initialize event domain services (validation, routing, processing)
+	l.InitEventServices()
+
+	// Initialize the user interface (registers routes)
 	l.UserInterface()
 
-	// Initialize Blossom blob storage server
-	if l.blossomServer, err = initializeBlossomServer(ctx, cfg, db); err != nil {
-		log.E.F("failed to initialize blossom server: %v", err)
-		// Continue without blossom server
-	} else if l.blossomServer != nil {
-		log.I.F("blossom blob storage server initialized")
-	}
-
 	// Ensure a relay identity secret key exists when subscriptions and NWC are enabled
 	if cfg.SubscriptionEnabled && cfg.NWCUri != "" {
 		if skb, e := db.GetOrCreateRelayIdentitySecret(); e != nil {
@@ -213,17 +468,31 @@ func Run(
 		}
 	}
 
-	if l.paymentProcessor, err = NewPaymentProcessor(ctx, cfg, db); err != nil {
-		// log.E.F("failed to create payment processor: %v", err)
-		// Continue without payment processor
-	} else {
-		if err = l.paymentProcessor.Start(); err != nil {
-			log.E.F("failed to start payment processor: %v", err)
+	// Initialize payment processor (only for Badger backend)
+	if badgerDB, ok := db.(*database.D); ok {
+		if l.paymentProcessor, err = NewPaymentProcessor(ctx, cfg, badgerDB); err != nil {
+			// log.E.F("failed to create payment processor: %v", err)
+			// Continue without payment processor
 		} else {
-			log.I.F("payment processor started successfully")
+			if err = l.paymentProcessor.Start(); err != nil {
+				log.E.F("failed to start payment processor: %v", err)
+			} else {
+				log.I.F("payment processor started successfully")
+			}
 		}
 	}
 
+	// Start rate limiter if enabled
+	if limiter != nil && limiter.IsEnabled() {
+		limiter.Start()
+		log.I.F("adaptive rate limiter started")
+	}
+
+	// Wait for database to be ready before accepting requests
+	log.I.F("waiting for database warmup to complete...")
+	<-db.Ready()
+	log.I.F("database ready, starting HTTP servers")
+
 	// Check if TLS is enabled
 	var tlsEnabled bool
 	var tlsServer *http.Server
@@ -310,6 +579,30 @@ func Run(
 			log.I.F("spider manager stopped")
 		}
 
+		// Stop directory spider if running
+		if l.directorySpider != nil {
+			l.directorySpider.Stop()
+			log.I.F("directory spider stopped")
+		}
+
+		// Stop rate limiter if running
+		if l.rateLimiter != nil && l.rateLimiter.IsEnabled() {
+			l.rateLimiter.Stop()
+			log.I.F("rate limiter stopped")
+		}
+
+		// Stop bunker server if running
+		if l.bunkerServer != nil {
+			l.bunkerServer.Stop()
+			log.I.F("bunker server stopped")
+		}
+
+		// Stop WireGuard server if running
+		if l.wireguardServer != nil {
+			l.wireguardServer.Stop()
+			log.I.F("WireGuard server stopped")
+		}
+
 		// Create shutdown context with timeout
 		shutdownCtx, cancelShutdown := context.WithTimeout(context.Background(), 10*time.Second)
 		defer cancelShutdown()

app/nip43_e2e_test.go

@@ -0,0 +1,593 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
+	"os"
+	"testing"
+	"time"
+
+	"next.orly.dev/app/config"
+	"next.orly.dev/pkg/acl"
+	"git.mleku.dev/mleku/nostr/crypto/keys"
+	"next.orly.dev/pkg/database"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"next.orly.dev/pkg/protocol/nip43"
+	"next.orly.dev/pkg/protocol/publish"
+	"git.mleku.dev/mleku/nostr/relayinfo"
+)
+
+// newTestListener creates a properly initialized Listener for testing
+func newTestListener(server *Server, ctx context.Context) *Listener {
+	listener := &Listener{
+		Server:         server,
+		ctx:            ctx,
+		writeChan:      make(chan publish.WriteRequest, 100),
+		writeDone:      make(chan struct{}),
+		messageQueue:   make(chan messageRequest, 100),
+		processingDone: make(chan struct{}),
+		subscriptions:  make(map[string]context.CancelFunc),
+	}
+
+	// Start write worker and message processor
+	go listener.writeWorker()
+	go listener.messageProcessor()
+
+	return listener
+}
+
+// closeTestListener properly closes a test listener
+func closeTestListener(listener *Listener) {
+	close(listener.writeChan)
+	<-listener.writeDone
+	close(listener.messageQueue)
+	<-listener.processingDone
+}
+
+// setupE2ETest creates a full test server for end-to-end testing
+func setupE2ETest(t *testing.T) (*Server, *httptest.Server, func()) {
+	tempDir, err := os.MkdirTemp("", "nip43_e2e_test_*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	db, err := database.New(ctx, cancel, tempDir, "info")
+	if err != nil {
+		os.RemoveAll(tempDir)
+		t.Fatalf("failed to open database: %v", err)
+	}
+
+	cfg := &config.C{
+		AppName:                "TestRelay",
+		NIP43Enabled:           true,
+		NIP43PublishEvents:     true,
+		NIP43PublishMemberList: true,
+		NIP43InviteExpiry:      24 * time.Hour,
+		RelayURL:               "wss://test.relay",
+		Listen:                 "localhost",
+		Port:                   3334,
+		ACLMode:                "none",
+		AuthRequired:           false,
+	}
+
+	// Generate admin keys
+	adminSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate admin secret: %v", err)
+	}
+	adminSigner, err := p8k.New()
+	if err != nil {
+		t.Fatalf("failed to create admin signer: %v", err)
+	}
+	if err = adminSigner.InitSec(adminSecret); err != nil {
+		t.Fatalf("failed to initialize admin signer: %v", err)
+	}
+	adminPubkey := adminSigner.Pub()
+
+	// Add admin to config for ACL
+	cfg.Admins = []string{hex.Enc(adminPubkey)}
+
+	server := &Server{
+		Ctx:           ctx,
+		Config:        cfg,
+		DB:            db,
+		publishers:    publish.New(NewPublisher(ctx)),
+		Admins:        [][]byte{adminPubkey},
+		InviteManager: nip43.NewInviteManager(cfg.NIP43InviteExpiry),
+		cfg:           cfg,
+		db:            db,
+	}
+
+	// Configure ACL registry
+	acl.Registry.SetMode(cfg.ACLMode)
+	if err = acl.Registry.Configure(cfg, db, ctx); err != nil {
+		db.Close()
+		os.RemoveAll(tempDir)
+		t.Fatalf("failed to configure ACL: %v", err)
+	}
+
+	server.mux = http.NewServeMux()
+
+	// Set up HTTP handlers
+	server.mux.HandleFunc(
+		"/", func(w http.ResponseWriter, r *http.Request) {
+			if r.Header.Get("Accept") == "application/nostr+json" {
+				server.HandleRelayInfo(w, r)
+				return
+			}
+			http.NotFound(w, r)
+		},
+	)
+
+	httpServer := httptest.NewServer(server.mux)
+
+	cleanup := func() {
+		httpServer.Close()
+		db.Close()
+		os.RemoveAll(tempDir)
+	}
+
+	return server, httpServer, cleanup
+}
+
+// TestE2E_RelayInfoIncludesNIP43 tests that NIP-43 is advertised in relay info
+func TestE2E_RelayInfoIncludesNIP43(t *testing.T) {
+	server, httpServer, cleanup := setupE2ETest(t)
+	defer cleanup()
+
+	// Make request to relay info endpoint
+	req, err := http.NewRequest("GET", httpServer.URL, nil)
+	if err != nil {
+		t.Fatalf("failed to create request: %v", err)
+	}
+	req.Header.Set("Accept", "application/nostr+json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("failed to make request: %v", err)
+	}
+	defer resp.Body.Close()
+
+	// Parse relay info
+	var info relayinfo.T
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
+		t.Fatalf("failed to decode relay info: %v", err)
+	}
+
+	// Verify NIP-43 is in supported NIPs
+	hasNIP43 := false
+	for _, nip := range info.Nips {
+		if nip == 43 {
+			hasNIP43 = true
+			break
+		}
+	}
+
+	if !hasNIP43 {
+		t.Error("NIP-43 not advertised in supported_nips")
+	}
+
+	// Verify server name
+	if info.Name != server.Config.AppName {
+		t.Errorf(
+			"wrong relay name: got %s, want %s", info.Name,
+			server.Config.AppName,
+		)
+	}
+}
+
+// TestE2E_CompleteJoinFlow tests the complete user join flow
+func TestE2E_CompleteJoinFlow(t *testing.T) {
+	server, _, cleanup := setupE2ETest(t)
+	defer cleanup()
+
+	// Step 1: Admin requests invite code
+	adminPubkey := server.Admins[0]
+	inviteEvent, err := server.HandleNIP43InviteRequest(adminPubkey)
+	if err != nil {
+		t.Fatalf("failed to generate invite: %v", err)
+	}
+
+	// Extract invite code
+	claimTag := inviteEvent.Tags.GetFirst([]byte("claim"))
+	if claimTag == nil || claimTag.Len() < 2 {
+		t.Fatal("invite event missing claim tag")
+	}
+	inviteCode := string(claimTag.T[1])
+
+	// Step 2: User creates join request
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userPubkey, err := keys.SecretBytesToPubKeyBytes(userSecret)
+	if err != nil {
+		t.Fatalf("failed to get user pubkey: %v", err)
+	}
+	signer, err := keys.SecretBytesToSigner(userSecret)
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+
+	joinEv := event.New()
+	joinEv.Kind = nip43.KindJoinRequest
+	copy(joinEv.Pubkey, userPubkey)
+	joinEv.Tags = tag.NewS()
+	joinEv.Tags.Append(tag.NewFromAny("-"))
+	joinEv.Tags.Append(tag.NewFromAny("claim", inviteCode))
+	joinEv.CreatedAt = time.Now().Unix()
+	joinEv.Content = []byte("")
+	if err = joinEv.Sign(signer); err != nil {
+		t.Fatalf("failed to sign join event: %v", err)
+	}
+
+	// Step 3: Process join request
+	listener := newTestListener(server, server.Ctx)
+	defer closeTestListener(listener)
+	err = listener.HandleNIP43JoinRequest(joinEv)
+	if err != nil {
+		t.Fatalf("failed to handle join request: %v", err)
+	}
+
+	// Step 4: Verify membership
+	isMember, err := server.DB.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if !isMember {
+		t.Error("user was not added as member")
+	}
+
+	membership, err := server.DB.GetNIP43Membership(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to get membership: %v", err)
+	}
+	if membership.InviteCode != inviteCode {
+		t.Errorf(
+			"wrong invite code: got %s, want %s", membership.InviteCode,
+			inviteCode,
+		)
+	}
+}
+
+// TestE2E_InviteCodeReuse tests that invite codes can only be used once
+func TestE2E_InviteCodeReuse(t *testing.T) {
+	server, _, cleanup := setupE2ETest(t)
+	defer cleanup()
+
+	// Generate invite code
+	code, err := server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	listener := newTestListener(server, server.Ctx)
+	defer closeTestListener(listener)
+
+	// First user uses the code
+	user1Secret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user1 secret: %v", err)
+	}
+	user1Pubkey, err := keys.SecretBytesToPubKeyBytes(user1Secret)
+	if err != nil {
+		t.Fatalf("failed to get user1 pubkey: %v", err)
+	}
+	signer1, err := keys.SecretBytesToSigner(user1Secret)
+	if err != nil {
+		t.Fatalf("failed to create signer1: %v", err)
+	}
+
+	joinEv1 := event.New()
+	joinEv1.Kind = nip43.KindJoinRequest
+	copy(joinEv1.Pubkey, user1Pubkey)
+	joinEv1.Tags = tag.NewS()
+	joinEv1.Tags.Append(tag.NewFromAny("-"))
+	joinEv1.Tags.Append(tag.NewFromAny("claim", code))
+	joinEv1.CreatedAt = time.Now().Unix()
+	joinEv1.Content = []byte("")
+	if err = joinEv1.Sign(signer1); err != nil {
+		t.Fatalf("failed to sign join event 1: %v", err)
+	}
+
+	err = listener.HandleNIP43JoinRequest(joinEv1)
+	if err != nil {
+		t.Fatalf("failed to handle join request 1: %v", err)
+	}
+
+	// Verify first user is member
+	isMember, err := server.DB.IsNIP43Member(user1Pubkey)
+	if err != nil {
+		t.Fatalf("failed to check user1 membership: %v", err)
+	}
+	if !isMember {
+		t.Error("user1 was not added")
+	}
+
+	// Second user tries to use same code
+	user2Secret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user2 secret: %v", err)
+	}
+	user2Pubkey, err := keys.SecretBytesToPubKeyBytes(user2Secret)
+	if err != nil {
+		t.Fatalf("failed to get user2 pubkey: %v", err)
+	}
+	signer2, err := keys.SecretBytesToSigner(user2Secret)
+	if err != nil {
+		t.Fatalf("failed to create signer2: %v", err)
+	}
+
+	joinEv2 := event.New()
+	joinEv2.Kind = nip43.KindJoinRequest
+	copy(joinEv2.Pubkey, user2Pubkey)
+	joinEv2.Tags = tag.NewS()
+	joinEv2.Tags.Append(tag.NewFromAny("-"))
+	joinEv2.Tags.Append(tag.NewFromAny("claim", code))
+	joinEv2.CreatedAt = time.Now().Unix()
+	joinEv2.Content = []byte("")
+	if err = joinEv2.Sign(signer2); err != nil {
+		t.Fatalf("failed to sign join event 2: %v", err)
+	}
+
+	// Should handle without error but not add user
+	err = listener.HandleNIP43JoinRequest(joinEv2)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+
+	// Verify second user is NOT member
+	isMember, err = server.DB.IsNIP43Member(user2Pubkey)
+	if err != nil {
+		t.Fatalf("failed to check user2 membership: %v", err)
+	}
+	if isMember {
+		t.Error("user2 was incorrectly added with reused code")
+	}
+}
+
+// TestE2E_MembershipListGeneration tests membership list event generation
+func TestE2E_MembershipListGeneration(t *testing.T) {
+	server, _, cleanup := setupE2ETest(t)
+	defer cleanup()
+
+	listener := newTestListener(server, server.Ctx)
+	defer closeTestListener(listener)
+
+	// Add multiple members
+	memberCount := 5
+	members := make([][]byte, memberCount)
+
+	for i := 0; i < memberCount; i++ {
+		userSecret, err := keys.GenerateSecretKey()
+		if err != nil {
+			t.Fatalf("failed to generate user secret %d: %v", i, err)
+		}
+		userPubkey, err := keys.SecretBytesToPubKeyBytes(userSecret)
+		if err != nil {
+			t.Fatalf("failed to get user pubkey %d: %v", i, err)
+		}
+		members[i] = userPubkey
+
+		// Add directly to database for speed
+		err = server.DB.AddNIP43Member(userPubkey, "code")
+		if err != nil {
+			t.Fatalf("failed to add member %d: %v", i, err)
+		}
+	}
+
+	// Generate membership list
+	err := listener.publishMembershipList()
+	if err != nil {
+		t.Fatalf("failed to publish membership list: %v", err)
+	}
+
+	// Note: In a real test, you would verify the event was published
+	// through the publishers system. For now, we just verify no error.
+}
+
+// TestE2E_ExpiredInviteCode tests that expired codes are rejected
+func TestE2E_ExpiredInviteCode(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "nip43_expired_test_*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	db, err := database.New(ctx, cancel, tempDir, "info")
+	if err != nil {
+		t.Fatalf("failed to open database: %v", err)
+	}
+	defer db.Close()
+
+	cfg := &config.C{
+		NIP43Enabled:      true,
+		NIP43InviteExpiry: 1 * time.Millisecond, // Very short expiry
+	}
+
+	server := &Server{
+		Ctx:           ctx,
+		Config:        cfg,
+		DB:            db,
+		publishers:    publish.New(NewPublisher(ctx)),
+		InviteManager: nip43.NewInviteManager(cfg.NIP43InviteExpiry),
+		cfg:           cfg,
+		db:            db,
+	}
+
+	listener := newTestListener(server, ctx)
+	defer closeTestListener(listener)
+
+	// Generate invite code
+	code, err := server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	// Wait for expiry
+	time.Sleep(10 * time.Millisecond)
+
+	// Try to use expired code
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userPubkey, err := keys.SecretBytesToPubKeyBytes(userSecret)
+	if err != nil {
+		t.Fatalf("failed to get user pubkey: %v", err)
+	}
+	signer, err := keys.SecretBytesToSigner(userSecret)
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+
+	joinEv := event.New()
+	joinEv.Kind = nip43.KindJoinRequest
+	copy(joinEv.Pubkey, userPubkey)
+	joinEv.Tags = tag.NewS()
+	joinEv.Tags.Append(tag.NewFromAny("-"))
+	joinEv.Tags.Append(tag.NewFromAny("claim", code))
+	joinEv.CreatedAt = time.Now().Unix()
+	joinEv.Content = []byte("")
+	if err = joinEv.Sign(signer); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	err = listener.HandleNIP43JoinRequest(joinEv)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+
+	// Verify user was NOT added
+	isMember, err := db.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if isMember {
+		t.Error("user was added with expired code")
+	}
+}
+
+// TestE2E_InvalidTimestampRejected tests that events with invalid timestamps are rejected
+func TestE2E_InvalidTimestampRejected(t *testing.T) {
+	server, _, cleanup := setupE2ETest(t)
+	defer cleanup()
+
+	listener := newTestListener(server, server.Ctx)
+	defer closeTestListener(listener)
+
+	// Generate invite code
+	code, err := server.InviteManager.GenerateCode()
+	if err != nil {
+		t.Fatalf("failed to generate invite code: %v", err)
+	}
+
+	// Create user
+	userSecret, err := keys.GenerateSecretKey()
+	if err != nil {
+		t.Fatalf("failed to generate user secret: %v", err)
+	}
+	userPubkey, err := keys.SecretBytesToPubKeyBytes(userSecret)
+	if err != nil {
+		t.Fatalf("failed to get user pubkey: %v", err)
+	}
+	signer, err := keys.SecretBytesToSigner(userSecret)
+	if err != nil {
+		t.Fatalf("failed to create signer: %v", err)
+	}
+
+	// Create join request with timestamp far in the past
+	joinEv := event.New()
+	joinEv.Kind = nip43.KindJoinRequest
+	copy(joinEv.Pubkey, userPubkey)
+	joinEv.Tags = tag.NewS()
+	joinEv.Tags.Append(tag.NewFromAny("-"))
+	joinEv.Tags.Append(tag.NewFromAny("claim", code))
+	joinEv.CreatedAt = time.Now().Unix() - 700 // More than 10 minutes ago
+	joinEv.Content = []byte("")
+	if err = joinEv.Sign(signer); err != nil {
+		t.Fatalf("failed to sign event: %v", err)
+	}
+
+	// Should handle without error but not add user
+	err = listener.HandleNIP43JoinRequest(joinEv)
+	if err != nil {
+		t.Fatalf("handler returned error: %v", err)
+	}
+
+	// Verify user was NOT added
+	isMember, err := server.DB.IsNIP43Member(userPubkey)
+	if err != nil {
+		t.Fatalf("failed to check membership: %v", err)
+	}
+	if isMember {
+		t.Error("user was added with invalid timestamp")
+	}
+}
+
+// BenchmarkJoinRequestProcessing benchmarks join request processing
+func BenchmarkJoinRequestProcessing(b *testing.B) {
+	tempDir, err := os.MkdirTemp("", "nip43_bench_*")
+	if err != nil {
+		b.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	db, err := database.New(ctx, cancel, tempDir, "error")
+	if err != nil {
+		b.Fatalf("failed to open database: %v", err)
+	}
+	defer db.Close()
+
+	cfg := &config.C{
+		NIP43Enabled:      true,
+		NIP43InviteExpiry: 24 * time.Hour,
+	}
+
+	server := &Server{
+		Ctx:           ctx,
+		Config:        cfg,
+		DB:            db,
+		publishers:    publish.New(NewPublisher(ctx)),
+		InviteManager: nip43.NewInviteManager(cfg.NIP43InviteExpiry),
+		cfg:           cfg,
+		db:            db,
+	}
+
+	listener := newTestListener(server, ctx)
+	defer closeTestListener(listener)
+
+	b.ResetTimer()
+
+	for i := 0; i < b.N; i++ {
+		// Generate unique user and code for each iteration
+		userSecret, _ := keys.GenerateSecretKey()
+		userPubkey, _ := keys.SecretBytesToPubKeyBytes(userSecret)
+		signer, _ := keys.SecretBytesToSigner(userSecret)
+		code, _ := server.InviteManager.GenerateCode()
+
+		joinEv := event.New()
+		joinEv.Kind = nip43.KindJoinRequest
+		copy(joinEv.Pubkey, userPubkey)
+		joinEv.Tags = tag.NewS()
+		joinEv.Tags.Append(tag.NewFromAny("-"))
+		joinEv.Tags.Append(tag.NewFromAny("claim", code))
+		joinEv.CreatedAt = time.Now().Unix()
+		joinEv.Content = []byte("")
+		joinEv.Sign(signer)
+
+		listener.HandleNIP43JoinRequest(joinEv)
+	}
+}

app/ok.go

@@ -1,9 +1,9 @@
 package app
 
 import (
-	"next.orly.dev/pkg/encoders/envelopes/eventenvelope"
-	"next.orly.dev/pkg/encoders/envelopes/okenvelope"
-	"next.orly.dev/pkg/encoders/reason"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/eventenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/envelopes/okenvelope"
+	"git.mleku.dev/mleku/nostr/encoders/reason"
 )
 
 // OK represents a function that processes events or operations, using provided

app/payment_processor.go

@@ -15,14 +15,14 @@ import (
 	"lol.mleku.dev/log"
 	"next.orly.dev/app/config"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/interfaces/signer/p8k"
+	"git.mleku.dev/mleku/nostr/interfaces/signer/p8k"
 	"next.orly.dev/pkg/database"
-	"next.orly.dev/pkg/encoders/bech32encoding"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/kind"
-	"next.orly.dev/pkg/encoders/tag"
-	"next.orly.dev/pkg/encoders/timestamp"
+	"git.mleku.dev/mleku/nostr/encoders/bech32encoding"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
+	"git.mleku.dev/mleku/nostr/encoders/timestamp"
 	"next.orly.dev/pkg/protocol/nwc"
 )
 

app/privileged_events_test.go

@@ -5,10 +5,10 @@ import (
 	"testing"
 	"time"
 
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/kind"
-	"next.orly.dev/pkg/encoders/tag"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
 )
 
 // Test helper to create a test event
@@ -54,9 +54,18 @@ func testPrivilegedEventFiltering(events event.S, authedPubkey []byte, aclMode s
 				// Check p tags
 				pTags := ev.Tags.GetAll([]byte("p"))
 				for _, pTag := range pTags {
-					var pt []byte
-					var err error
-					if pt, err = hex.Dec(string(pTag.Value())); err != nil {
+					// First try binary format (optimized storage)
+					if pt := pTag.ValueBinary(); pt != nil {
+						if bytes.Equal(pt, authedPubkey) {
+							authorized = true
+							break
+						}
+						continue
+					}
+					// Fall back to hex decoding for non-binary values
+					// Use ValueHex() which handles both binary and hex storage formats
+					pt, err := hex.Dec(string(pTag.ValueHex()))
+					if err != nil {
 						continue
 					}
 					if bytes.Equal(pt, authedPubkey) {
@@ -395,6 +404,82 @@ func TestPrivilegedEventEdgeCases(t *testing.T) {
 	}
 }
 
+// TestPrivilegedEventsWithACLNone tests that privileged events are accessible
+// to anyone when ACL mode is set to "none" (open relay)
+func TestPrivilegedEventsWithACLNone(t *testing.T) {
+	authorPubkey := []byte("author-pubkey-12345")
+	recipientPubkey := []byte("recipient-pubkey-67")
+	unauthorizedPubkey := []byte("unauthorized-pubkey")
+
+	// Create a privileged event (encrypted DM)
+	privilegedEvent := createTestEvent(
+		"event-id-1",
+		hex.Enc(authorPubkey),
+		"private message",
+		kind.EncryptedDirectMessage.K,
+		createPTag(hex.Enc(recipientPubkey)),
+	)
+
+	tests := []struct {
+		name         string
+		authedPubkey []byte
+		aclMode      string
+		accessLevel  string
+		shouldAllow  bool
+		description  string
+	}{
+		{
+			name:         "ACL none - unauthorized user can see privileged event",
+			authedPubkey: unauthorizedPubkey,
+			aclMode:      "none",
+			accessLevel:  "write", // default for ACL=none
+			shouldAllow:  true,
+			description:  "When ACL is 'none', privileged events should be visible to anyone",
+		},
+		{
+			name:         "ACL none - unauthenticated user can see privileged event",
+			authedPubkey: nil,
+			aclMode:      "none",
+			accessLevel:  "write", // default for ACL=none
+			shouldAllow:  true,
+			description:  "When ACL is 'none', even unauthenticated users can see privileged events",
+		},
+		{
+			name:         "ACL managed - unauthorized user cannot see privileged event",
+			authedPubkey: unauthorizedPubkey,
+			aclMode:      "managed",
+			accessLevel:  "write",
+			shouldAllow:  false,
+			description:  "When ACL is 'managed', unauthorized users cannot see privileged events",
+		},
+		{
+			name:         "ACL follows - unauthorized user cannot see privileged event",
+			authedPubkey: unauthorizedPubkey,
+			aclMode:      "follows",
+			accessLevel:  "write",
+			shouldAllow:  false,
+			description:  "When ACL is 'follows', unauthorized users cannot see privileged events",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			events := event.S{privilegedEvent}
+			filtered := testPrivilegedEventFiltering(events, tt.authedPubkey, tt.aclMode, tt.accessLevel)
+
+			if tt.shouldAllow {
+				if len(filtered) != 1 {
+					t.Errorf("%s: Expected event to be allowed, but it was filtered out. %s", tt.name, tt.description)
+				}
+			} else {
+				if len(filtered) != 0 {
+					t.Errorf("%s: Expected event to be filtered out, but it was allowed. %s", tt.name, tt.description)
+				}
+			}
+		})
+	}
+}
+
 func TestPrivilegedEventPolicyIntegration(t *testing.T) {
 	// Test that the policy system also correctly handles privileged events
 	// This tests the policy.go implementation

app/publisher.go

@@ -9,12 +9,13 @@ import (
 	"github.com/gorilla/websocket"
 	"lol.mleku.dev/log"
 	"next.orly.dev/pkg/acl"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/filter"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/kind"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/kind"
 	"next.orly.dev/pkg/interfaces/publisher"
 	"next.orly.dev/pkg/interfaces/typer"
+	"next.orly.dev/pkg/policy"
 	"next.orly.dev/pkg/protocol/publish"
 	"next.orly.dev/pkg/utils"
 )
@@ -28,6 +29,7 @@ type Subscription struct {
 	remote       string
 	AuthedPubkey []byte
 	Receiver     event.C // Channel for delivering events to this subscription
+	AuthRequired bool    // Whether ACL requires authentication for privileged events
 	*filter.S
 }
 
@@ -58,6 +60,11 @@ type W struct {
 
 	// AuthedPubkey is the authenticated pubkey associated with the listener (if any).
 	AuthedPubkey []byte
+
+	// AuthRequired indicates whether the ACL in operation requires auth. If
+	// this is set to true, the publisher will not publish privileged or other
+	// restricted events to non-authed listeners, otherwise, it will.
+	AuthRequired bool
 }
 
 func (w *W) Type() (typeName string) { return Type }
@@ -87,7 +94,6 @@ func NewPublisher(c context.Context) (publisher *P) {
 
 func (p *P) Type() (typeName string) { return Type }
 
-
 // Receive handles incoming messages to manage websocket listener subscriptions
 // and associated filters.
 //
@@ -120,12 +126,14 @@ func (p *P) Receive(msg typer.T) {
 		if subs, ok := p.Map[m.Conn]; !ok {
 			subs = make(map[string]Subscription)
 			subs[m.Id] = Subscription{
-				S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey, Receiver: m.Receiver,
+				S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey,
+				Receiver: m.Receiver, AuthRequired: m.AuthRequired,
 			}
 			p.Map[m.Conn] = subs
 		} else {
 			subs[m.Id] = Subscription{
-				S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey, Receiver: m.Receiver,
+				S: m.Filters, remote: m.remote, AuthedPubkey: m.AuthedPubkey,
+				Receiver: m.Receiver, AuthRequired: m.AuthRequired,
 			}
 		}
 	}
@@ -174,35 +182,16 @@ func (p *P) Deliver(ev *event.E) {
 	for _, d := range deliveries {
 		// If the event is privileged, enforce that the subscriber's authed pubkey matches
 		// either the event pubkey or appears in any 'p' tag of the event.
-		if kind.IsPrivileged(ev.Kind) {
-			if len(d.sub.AuthedPubkey) == 0 {
-				// Not authenticated - cannot see privileged events
-				log.D.F("subscription delivery DENIED for privileged event %s to %s (not authenticated)",
-					hex.Enc(ev.ID), d.sub.remote)
-				continue
-			}
-
+		// Only check authentication if AuthRequired is true (ACL is active)
+		if kind.IsPrivileged(ev.Kind) && d.sub.AuthRequired {
 			pk := d.sub.AuthedPubkey
-			allowed := false
-			// Direct author match
-			if utils.FastEqual(ev.Pubkey, pk) {
-				allowed = true
-			} else if ev.Tags != nil {
-				for _, pTag := range ev.Tags.GetAll([]byte("p")) {
-					// pTag.Value() returns []byte hex string; decode to bytes
-					dec, derr := hex.Dec(string(pTag.Value()))
-					if derr != nil {
-						continue
-					}
-					if utils.FastEqual(dec, pk) {
-						allowed = true
-						break
-					}
-				}
-			}
-			if !allowed {
-				log.D.F("subscription delivery DENIED for privileged event %s to %s (auth mismatch)",
-					hex.Enc(ev.ID), d.sub.remote)
+
+			// Use centralized IsPartyInvolved function for consistent privilege checking
+			if !policy.IsPartyInvolved(ev, pk) {
+				log.D.F(
+					"subscription delivery DENIED for privileged event %s to %s (not authenticated or not a party involved)",
+					hex.Enc(ev.ID), d.sub.remote,
+				)
 				// Skip delivery for this subscriber
 				continue
 			}
@@ -225,26 +214,37 @@ func (p *P) Deliver(ev *event.E) {
 			}
 
 			if hasPrivateTag {
-				canSeePrivate := p.canSeePrivateEvent(d.sub.AuthedPubkey, privatePubkey, d.sub.remote)
+				canSeePrivate := p.canSeePrivateEvent(
+					d.sub.AuthedPubkey, privatePubkey, d.sub.remote,
+				)
 				if !canSeePrivate {
-					log.D.F("subscription delivery DENIED for private event %s to %s (unauthorized)",
-						hex.Enc(ev.ID), d.sub.remote)
+					log.D.F(
+						"subscription delivery DENIED for private event %s to %s (unauthorized)",
+						hex.Enc(ev.ID), d.sub.remote,
+					)
 					continue
 				}
-				log.D.F("subscription delivery ALLOWED for private event %s to %s (authorized)",
-					hex.Enc(ev.ID), d.sub.remote)
+				log.D.F(
+					"subscription delivery ALLOWED for private event %s to %s (authorized)",
+					hex.Enc(ev.ID), d.sub.remote,
+				)
 			}
 		}
 
 		// Send event to the subscription's receiver channel
 		// The consumer goroutine (in handle-req.go) will read from this channel
 		// and forward it to the client via the write channel
-		log.D.F("attempting delivery of event %s (kind=%d) to subscription %s @ %s",
-			hex.Enc(ev.ID), ev.Kind, d.id, d.sub.remote)
+		log.D.F(
+			"attempting delivery of event %s (kind=%d) to subscription %s @ %s",
+			hex.Enc(ev.ID), ev.Kind, d.id, d.sub.remote,
+		)
 
 		// Check if receiver channel exists
 		if d.sub.Receiver == nil {
-			log.E.F("subscription %s has nil receiver channel for %s", d.id, d.sub.remote)
+			log.E.F(
+				"subscription %s has nil receiver channel for %s", d.id,
+				d.sub.remote,
+			)
 			continue
 		}
 
@@ -253,11 +253,15 @@ func (p *P) Deliver(ev *event.E) {
 		case <-p.c.Done():
 			continue
 		case d.sub.Receiver <- ev:
-			log.D.F("subscription delivery QUEUED: event=%s to=%s sub=%s",
-				hex.Enc(ev.ID), d.sub.remote, d.id)
+			log.D.F(
+				"subscription delivery QUEUED: event=%s to=%s sub=%s",
+				hex.Enc(ev.ID), d.sub.remote, d.id,
+			)
 		case <-time.After(DefaultWriteTimeout):
-			log.E.F("subscription delivery TIMEOUT: event=%s to=%s sub=%s",
-				hex.Enc(ev.ID), d.sub.remote, d.id)
+			log.E.F(
+				"subscription delivery TIMEOUT: event=%s to=%s sub=%s",
+				hex.Enc(ev.ID), d.sub.remote, d.id,
+			)
 			// Receiver channel is full - subscription consumer is stuck or slow
 			// The subscription should be removed by the cleanup logic
 		}
@@ -285,7 +289,9 @@ func (p *P) removeSubscriberId(ws *websocket.Conn, id string) {
 
 // SetWriteChan stores the write channel for a websocket connection
 // If writeChan is nil, the entry is removed from the map
-func (p *P) SetWriteChan(conn *websocket.Conn, writeChan chan publish.WriteRequest) {
+func (p *P) SetWriteChan(
+	conn *websocket.Conn, writeChan chan publish.WriteRequest,
+) {
 	p.Mx.Lock()
 	defer p.Mx.Unlock()
 	if writeChan == nil {
@@ -296,7 +302,9 @@ func (p *P) SetWriteChan(conn *websocket.Conn, writeChan chan publish.WriteReque
 }
 
 // GetWriteChan returns the write channel for a websocket connection
-func (p *P) GetWriteChan(conn *websocket.Conn) (chan publish.WriteRequest, bool) {
+func (p *P) GetWriteChan(conn *websocket.Conn) (
+	chan publish.WriteRequest, bool,
+) {
 	p.Mx.RLock()
 	defer p.Mx.RUnlock()
 	ch, ok := p.WriteChans[conn]
@@ -312,8 +320,71 @@ func (p *P) removeSubscriber(ws *websocket.Conn) {
 	delete(p.WriteChans, ws)
 }
 
+// HasActiveNIP46Signer checks if there's an active subscription for kind 24133
+// where the given pubkey is involved (either as author filter or in #p tag filter).
+// This is used to authenticate clients by proving a signer is connected for that pubkey.
+func (p *P) HasActiveNIP46Signer(signerPubkey []byte) bool {
+	const kindNIP46 = 24133
+	p.Mx.RLock()
+	defer p.Mx.RUnlock()
+
+	for _, subs := range p.Map {
+		for _, sub := range subs {
+			if sub.S == nil {
+				continue
+			}
+			for _, f := range *sub.S {
+				if f == nil || f.Kinds == nil {
+					continue
+				}
+				// Check if filter is for kind 24133
+				hasNIP46Kind := false
+				for _, k := range f.Kinds.K {
+					if k.K == kindNIP46 {
+						hasNIP46Kind = true
+						break
+					}
+				}
+				if !hasNIP46Kind {
+					continue
+				}
+				// Check if the signer pubkey matches the #p tag filter
+				if f.Tags != nil {
+					pTag := f.Tags.GetFirst([]byte("p"))
+					if pTag != nil && pTag.Len() >= 2 {
+						for i := 1; i < pTag.Len(); i++ {
+							tagValue := pTag.T[i]
+							// Compare - handle both binary and hex formats
+							if len(tagValue) == 32 && len(signerPubkey) == 32 {
+								if utils.FastEqual(tagValue, signerPubkey) {
+									return true
+								}
+							} else if len(tagValue) == 64 && len(signerPubkey) == 32 {
+								// tagValue is hex, signerPubkey is binary
+								if string(tagValue) == hex.Enc(signerPubkey) {
+									return true
+								}
+							} else if len(tagValue) == 32 && len(signerPubkey) == 64 {
+								// tagValue is binary, signerPubkey is hex
+								if hex.Enc(tagValue) == string(signerPubkey) {
+									return true
+								}
+							} else if utils.FastEqual(tagValue, signerPubkey) {
+								return true
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+	return false
+}
+
 // canSeePrivateEvent checks if the authenticated user can see an event with a private tag
-func (p *P) canSeePrivateEvent(authedPubkey, privatePubkey []byte, remote string) (canSee bool) {
+func (p *P) canSeePrivateEvent(
+	authedPubkey, privatePubkey []byte, remote string,
+) (canSee bool) {
 	// If no authenticated user, deny access
 	if len(authedPubkey) == 0 {
 		return false

app/server.go

@@ -17,18 +17,29 @@ import (
 	"lol.mleku.dev/chk"
 	"next.orly.dev/app/config"
 	"next.orly.dev/pkg/acl"
+	"next.orly.dev/pkg/blossom"
 	"next.orly.dev/pkg/database"
-	"next.orly.dev/pkg/encoders/event"
-	"next.orly.dev/pkg/encoders/filter"
-	"next.orly.dev/pkg/encoders/hex"
-	"next.orly.dev/pkg/encoders/tag"
+	"next.orly.dev/pkg/event/authorization"
+	"next.orly.dev/pkg/event/processing"
+	"next.orly.dev/pkg/event/routing"
+	"next.orly.dev/pkg/event/validation"
+	"git.mleku.dev/mleku/nostr/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/filter"
+	"git.mleku.dev/mleku/nostr/encoders/hex"
+	"git.mleku.dev/mleku/nostr/encoders/tag"
 	"next.orly.dev/pkg/policy"
-	"next.orly.dev/pkg/protocol/auth"
-	"next.orly.dev/pkg/protocol/httpauth"
+	"git.mleku.dev/mleku/nostr/protocol/auth"
+	"git.mleku.dev/mleku/nostr/httpauth"
+	"next.orly.dev/pkg/protocol/graph"
+	"next.orly.dev/pkg/protocol/nip43"
 	"next.orly.dev/pkg/protocol/publish"
+	"next.orly.dev/pkg/bunker"
+	"next.orly.dev/pkg/cashu/issuer"
+	"next.orly.dev/pkg/cashu/verifier"
+	"next.orly.dev/pkg/ratelimit"
 	"next.orly.dev/pkg/spider"
 	dsync "next.orly.dev/pkg/sync"
-	blossom "next.orly.dev/pkg/blossom"
+	"next.orly.dev/pkg/wireguard"
 )
 
 type Server struct {
@@ -38,7 +49,7 @@ type Server struct {
 	publishers *publish.S
 	Admins     [][]byte
 	Owners     [][]byte
-	*database.D
+	DB         database.Database // Changed from embedded *database.D to interface field
 
 	// optional reverse proxy for dev web server
 	devProxy *httputil.ReverseProxy
@@ -47,14 +58,39 @@ type Server struct {
 	challengeMutex sync.RWMutex
 	challenges     map[string][]byte
 
-	paymentProcessor *PaymentProcessor
-	sprocketManager  *SprocketManager
-	policyManager    *policy.P
-	spiderManager    *spider.Spider
-	syncManager      *dsync.Manager
-	relayGroupMgr    *dsync.RelayGroupManager
-	clusterManager   *dsync.ClusterManager
-	blossomServer    *blossom.Server
+	// Message processing pause mutex for policy/follow list updates
+	// Use RLock() for normal message processing, Lock() for updates
+	messagePauseMutex sync.RWMutex
+
+	paymentProcessor  *PaymentProcessor
+	sprocketManager   *SprocketManager
+	policyManager     *policy.P
+	spiderManager     *spider.Spider
+	directorySpider   *spider.DirectorySpider
+	syncManager       *dsync.Manager
+	relayGroupMgr     *dsync.RelayGroupManager
+	clusterManager    *dsync.ClusterManager
+	blossomServer     *blossom.Server
+	InviteManager     *nip43.InviteManager
+	graphExecutor     *graph.Executor
+	rateLimiter       *ratelimit.Limiter
+	cfg               *config.C
+	db                database.Database // Changed from *database.D to interface
+
+	// Domain services for event handling
+	eventValidator   *validation.Service
+	eventAuthorizer  *authorization.Service
+	eventRouter      *routing.DefaultRouter
+	eventProcessor   *processing.Service
+
+	// WireGuard VPN and NIP-46 Bunker
+	wireguardServer *wireguard.Server
+	bunkerServer    *bunker.Server
+	subnetPool      *wireguard.SubnetPool
+
+	// Cashu access token system (NIP-XX)
+	CashuIssuer   *issuer.Issuer
+	CashuVerifier *verifier.Verifier
 }
 
 // isIPBlacklisted checks if an IP address is blacklisted using the managed ACL system
@@ -87,22 +123,33 @@ func (s *Server) isIPBlacklisted(remote string) bool {
 }
 
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	// Set comprehensive CORS headers for proxy compatibility
-	w.Header().Set("Access-Control-Allow-Origin", "*")
-	w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
-	w.Header().Set("Access-Control-Allow-Headers",
-		"Origin, X-Requested-With, Content-Type, Accept, Authorization, "+
-			"X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Real-IP, "+
-			"Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version, "+
-			"Sec-WebSocket-Protocol, Sec-WebSocket-Extensions")
-	w.Header().Set("Access-Control-Allow-Credentials", "true")
-	w.Header().Set("Access-Control-Max-Age", "86400")
+	// Check if this is a blossom-related path (needs CORS headers)
+	path := r.URL.Path
+	isBlossomPath := path == "/upload" || path == "/media" ||
+		path == "/mirror" || path == "/report" ||
+		strings.HasPrefix(path, "/list/") ||
+		strings.HasPrefix(path, "/blossom/") ||
+		(len(path) == 65 && path[0] == '/') // /<sha256> blob downloads
 
-	// Add proxy-friendly headers
-	w.Header().Set("Vary", "Origin, Access-Control-Request-Method, Access-Control-Request-Headers")
+	// Set CORS headers for all blossom-related requests
+	if isBlossomPath {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, PUT, DELETE, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Authorization, authorization, Content-Type, content-type, X-SHA-256, x-sha-256, X-Content-Length, x-content-length, X-Content-Type, x-content-type, Accept, accept")
+		w.Header().Set("Access-Control-Expose-Headers", "X-Reason, Content-Length, Content-Type, Accept-Ranges")
+		w.Header().Set("Access-Control-Max-Age", "86400")
 
-	// Handle preflight OPTIONS requests
-	if r.Method == "OPTIONS" {
+		// Handle preflight OPTIONS requests for blossom paths
+		if r.Method == "OPTIONS" {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+	} else if r.Method == "OPTIONS" {
+		// Handle OPTIONS for non-blossom paths
+		if s.mux != nil {
+			s.mux.ServeHTTP(w, r)
+			return
+		}
 		w.WriteHeader(http.StatusOK)
 		return
 	}
@@ -137,6 +184,16 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) ServiceURL(req *http.Request) (url string) {
+	// Use configured RelayURL if available
+	if s.Config != nil && s.Config.RelayURL != "" {
+		relayURL := strings.TrimSuffix(s.Config.RelayURL, "/")
+		// Ensure it has a protocol
+		if !strings.HasPrefix(relayURL, "http://") && !strings.HasPrefix(relayURL, "https://") {
+			relayURL = "http://" + relayURL
+		}
+		return relayURL
+	}
+
 	proto := req.Header.Get("X-Forwarded-Proto")
 	if proto == "" {
 		if req.TLS != nil {
@@ -207,6 +264,15 @@ func (s *Server) UserInterface() {
 					origDirector(req)
 					req.Host = target.Host
 				}
+				// Suppress noisy "context canceled" errors from browser navigation
+				s.devProxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
+					if r.Context().Err() == context.Canceled {
+						// Browser canceled the request - this is normal, don't log it
+						return
+					}
+					log.Printf("proxy error: %v", err)
+					http.Error(w, "Bad Gateway", http.StatusBadGateway)
+				}
 			}
 		}
 	}
@@ -241,12 +307,18 @@ func (s *Server) UserInterface() {
 	s.mux.HandleFunc("/api/sprocket/update", s.handleSprocketUpdate)
 	s.mux.HandleFunc("/api/sprocket/restart", s.handleSprocketRestart)
 	s.mux.HandleFunc("/api/sprocket/versions", s.handleSprocketVersions)
-	s.mux.HandleFunc("/api/sprocket/delete-version", s.handleSprocketDeleteVersion)
+	s.mux.HandleFunc(
+		"/api/sprocket/delete-version", s.handleSprocketDeleteVersion,
+	)
 	s.mux.HandleFunc("/api/sprocket/config", s.handleSprocketConfig)
 	// NIP-86 management endpoint
 	s.mux.HandleFunc("/api/nip86", s.handleNIP86Management)
 	// ACL mode endpoint
 	s.mux.HandleFunc("/api/acl-mode", s.handleACLMode)
+	// Log viewer endpoints (owner only)
+	s.mux.HandleFunc("/api/logs", s.handleGetLogs)
+	s.mux.HandleFunc("/api/logs/clear", s.handleClearLogs)
+	s.mux.HandleFunc("/api/logs/level", s.handleLogLevel)
 
 	// Sync endpoints for distributed synchronization
 	if s.syncManager != nil {
@@ -257,8 +329,17 @@ func (s *Server) UserInterface() {
 
 	// Blossom blob storage API endpoint
 	if s.blossomServer != nil {
+		// Primary routes under /blossom/
 		s.mux.HandleFunc("/blossom/", s.blossomHandler)
-		log.Printf("Blossom blob storage API enabled at /blossom")
+		// Root-level routes for clients that expect blossom at root (like Jumble)
+		s.mux.HandleFunc("/upload", s.blossomRootHandler)
+		s.mux.HandleFunc("/list/", s.blossomRootHandler)
+		s.mux.HandleFunc("/media", s.blossomRootHandler)
+		s.mux.HandleFunc("/mirror", s.blossomRootHandler)
+		s.mux.HandleFunc("/report", s.blossomRootHandler)
+		log.Printf("Blossom blob storage API enabled at /blossom and root")
+	} else {
+		log.Printf("WARNING: Blossom server is nil, routes not registered")
 	}
 
 	// Cluster replication API endpoints
@@ -267,6 +348,23 @@ func (s *Server) UserInterface() {
 		s.mux.HandleFunc("/cluster/events", s.clusterManager.HandleEventsRange)
 		log.Printf("Cluster replication API enabled at /cluster")
 	}
+
+	// WireGuard VPN and Bunker API endpoints
+	// These are always registered but will return errors if not enabled
+	s.mux.HandleFunc("/api/wireguard/config", s.handleWireGuardConfig)
+	s.mux.HandleFunc("/api/wireguard/regenerate", s.handleWireGuardRegenerate)
+	s.mux.HandleFunc("/api/wireguard/status", s.handleWireGuardStatus)
+	s.mux.HandleFunc("/api/wireguard/audit", s.handleWireGuardAudit)
+	s.mux.HandleFunc("/api/bunker/url", s.handleBunkerURL)
+	s.mux.HandleFunc("/api/bunker/info", s.handleBunkerInfo)
+
+	// Cashu access token endpoints (NIP-XX)
+	s.mux.HandleFunc("/cashu/mint", s.handleCashuMint)
+	s.mux.HandleFunc("/cashu/keysets", s.handleCashuKeysets)
+	s.mux.HandleFunc("/cashu/info", s.handleCashuInfo)
+	if s.CashuIssuer != nil {
+		log.Printf("Cashu access token API enabled at /cashu")
+	}
 }
 
 // handleFavicon serves orly-favicon.png as favicon.ico
@@ -277,6 +375,12 @@ func (s *Server) handleFavicon(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// If web UI is disabled without a proxy, return 404
+	if s.Config != nil && s.Config.WebDisableEmbedded {
+		http.NotFound(w, r)
+		return
+	}
+
 	// Serve orly-favicon.png as favicon.ico from embedded web app
 	w.Header().Set("Content-Type", "image/png")
 	w.Header().Set("Cache-Control", "public, max-age=86400") // Cache for 1 day
@@ -297,6 +401,12 @@ func (s *Server) handleLoginInterface(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// If web UI is disabled without a proxy, return 404
+	if s.Config != nil && s.Config.WebDisableEmbedded {
+		http.NotFound(w, r)
+		return
+	}
+
 	// Serve embedded web interface
 	ServeEmbeddedWeb(w, r)
 }
@@ -339,7 +449,9 @@ func (s *Server) handleAuthChallenge(w http.ResponseWriter, r *http.Request) {
 
 	jsonData, err := json.Marshal(response)
 	if chk.E(err) {
-		http.Error(w, "Error generating challenge", http.StatusInternalServerError)
+		http.Error(
+			w, "Error generating challenge", http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -543,22 +655,28 @@ func (s *Server) handleExport(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Validate NIP-98 authentication
-	valid, pubkey, err := httpauth.CheckAuth(r)
-	if chk.E(err) || !valid {
-		errorMsg := "NIP-98 authentication validation failed"
-		if err != nil {
-			errorMsg = err.Error()
+	// Skip authentication and permission checks when ACL is "none" (open relay mode)
+	if acl.Registry.Active.Load() != "none" {
+		// Validate NIP-98 authentication
+		valid, pubkey, err := httpauth.CheckAuth(r)
+		if chk.E(err) || !valid {
+			errorMsg := "NIP-98 authentication validation failed"
+			if err != nil {
+				errorMsg = err.Error()
+			}
+			http.Error(w, errorMsg, http.StatusUnauthorized)
+			return
 		}
-		http.Error(w, errorMsg, http.StatusUnauthorized)
-		return
-	}
 
-	// Check permissions - require write, admin, or owner level
-	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
-	if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
-		http.Error(w, "Write, admin, or owner permission required", http.StatusForbidden)
-		return
+		// Check permissions - require write, admin, or owner level
+		accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+		if accessLevel != "write" && accessLevel != "admin" && accessLevel != "owner" {
+			http.Error(
+				w, "Write, admin, or owner permission required",
+				http.StatusForbidden,
+			)
+			return
+		}
 	}
 
 	// Parse pubkeys from request
@@ -606,10 +724,12 @@ func (s *Server) handleExport(w http.ResponseWriter, r *http.Request) {
 	}
 
 	w.Header().Set("Content-Type", "application/x-ndjson")
-	w.Header().Set("Content-Disposition", "attachment; filename=\""+filename+"\"")
+	w.Header().Set(
+		"Content-Disposition", "attachment; filename=\""+filename+"\"",
+	)
 
 	// Stream export
-	s.D.Export(s.Ctx, w, pks...)
+	s.DB.Export(s.Ctx, w, pks...)
 }
 
 // handleEventsMine returns the authenticated user's events in JSON format with pagination using NIP-98 authentication.
@@ -652,7 +772,7 @@ func (s *Server) handleEventsMine(w http.ResponseWriter, r *http.Request) {
 	}
 
 	log.Printf("DEBUG: Querying events for pubkey: %s", hex.Enc(pubkey))
-	events, err := s.D.QueryEvents(s.Ctx, f)
+	events, err := s.DB.QueryEvents(s.Ctx, f)
 	if chk.E(err) {
 		log.Printf("DEBUG: QueryEvents failed: %v", err)
 		http.Error(w, "Failed to query events", http.StatusInternalServerError)
@@ -707,22 +827,27 @@ func (s *Server) handleImport(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Validate NIP-98 authentication
-	valid, pubkey, err := httpauth.CheckAuth(r)
-	if chk.E(err) || !valid {
-		errorMsg := "NIP-98 authentication validation failed"
-		if err != nil {
-			errorMsg = err.Error()
+	// Skip authentication and permission checks when ACL is "none" (open relay mode)
+	if acl.Registry.Active.Load() != "none" {
+		// Validate NIP-98 authentication
+		valid, pubkey, err := httpauth.CheckAuth(r)
+		if chk.E(err) || !valid {
+			errorMsg := "NIP-98 authentication validation failed"
+			if err != nil {
+				errorMsg = err.Error()
+			}
+			http.Error(w, errorMsg, http.StatusUnauthorized)
+			return
 		}
-		http.Error(w, errorMsg, http.StatusUnauthorized)
-		return
-	}
 
-	// Check permissions - require admin or owner level
-	accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
-	if accessLevel != "admin" && accessLevel != "owner" {
-		http.Error(w, "Admin or owner permission required", http.StatusForbidden)
-		return
+		// Check permissions - require admin or owner level
+		accessLevel := acl.Registry.GetAccessLevel(pubkey, r.RemoteAddr)
+		if accessLevel != "admin" && accessLevel != "owner" {
+			http.Error(
+				w, "Admin or owner permission required", http.StatusForbidden,
+			)
+			return
+		}
 	}
 
 	ct := r.Header.Get("Content-Type")
@@ -737,13 +862,13 @@ func (s *Server) handleImport(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		defer file.Close()
-		s.D.Import(file)
+		s.DB.Import(file)
 	} else {
 		if r.Body == nil {
 			http.Error(w, "Empty request body", http.StatusBadRequest)
 			return
 		}
-		s.D.Import(r.Body)
+		s.DB.Import(r.Body)
 	}
 
 	w.Header().Set("Content-Type", "application/json")
@@ -781,7 +906,9 @@ func (s *Server) handleSprocketStatus(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	jsonData, err := json.Marshal(status)
 	if chk.E(err) {
-		http.Error(w, "Error generating response", http.StatusInternalServerError)
+		http.Error(
+			w, "Error generating response", http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -822,7 +949,10 @@ func (s *Server) handleSprocketUpdate(w http.ResponseWriter, r *http.Request) {
 
 	// Update the sprocket script
 	if err := s.sprocketManager.UpdateSprocket(string(body)); chk.E(err) {
-		http.Error(w, fmt.Sprintf("Failed to update sprocket: %v", err), http.StatusInternalServerError)
+		http.Error(
+			w, fmt.Sprintf("Failed to update sprocket: %v", err),
+			http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -857,7 +987,10 @@ func (s *Server) handleSprocketRestart(w http.ResponseWriter, r *http.Request) {
 
 	// Restart the sprocket script
 	if err := s.sprocketManager.RestartSprocket(); chk.E(err) {
-		http.Error(w, fmt.Sprintf("Failed to restart sprocket: %v", err), http.StatusInternalServerError)
+		http.Error(
+			w, fmt.Sprintf("Failed to restart sprocket: %v", err),
+			http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -866,7 +999,9 @@ func (s *Server) handleSprocketRestart(w http.ResponseWriter, r *http.Request) {
 }
 
 // handleSprocketVersions returns all sprocket script versions
-func (s *Server) handleSprocketVersions(w http.ResponseWriter, r *http.Request) {
+func (s *Server) handleSprocketVersions(
+	w http.ResponseWriter, r *http.Request,
+) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
@@ -892,14 +1027,19 @@ func (s *Server) handleSprocketVersions(w http.ResponseWriter, r *http.Request)
 
 	versions, err := s.sprocketManager.GetSprocketVersions()
 	if chk.E(err) {
-		http.Error(w, fmt.Sprintf("Failed to get sprocket versions: %v", err), http.StatusInternalServerError)
+		http.Error(
+			w, fmt.Sprintf("Failed to get sprocket versions: %v", err),
+			http.StatusInternalServerError,
+		)
 		return
 	}
 
 	w.Header().Set("Content-Type", "application/json")
 	jsonData, err := json.Marshal(versions)
 	if chk.E(err) {
-		http.Error(w, "Error generating response", http.StatusInternalServerError)
+		http.Error(
+			w, "Error generating response", http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -907,7 +1047,9 @@ func (s *Server) handleSprocketVersions(w http.ResponseWriter, r *http.Request)
 }
 
 // handleSprocketDeleteVersion deletes a specific sprocket version
-func (s *Server) handleSprocketDeleteVersion(w http.ResponseWriter, r *http.Request) {
+func (s *Server) handleSprocketDeleteVersion(
+	w http.ResponseWriter, r *http.Request,
+) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
@@ -953,7 +1095,10 @@ func (s *Server) handleSprocketDeleteVersion(w http.ResponseWriter, r *http.Requ
 
 	// Delete the sprocket version
 	if err := s.sprocketManager.DeleteSprocketVersion(request.Filename); chk.E(err) {
-		http.Error(w, fmt.Sprintf("Failed to delete sprocket version: %v", err), http.StatusInternalServerError)
+		http.Error(
+			w, fmt.Sprintf("Failed to delete sprocket version: %v", err),
+			http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -978,7 +1123,9 @@ func (s *Server) handleSprocketConfig(w http.ResponseWriter, r *http.Request) {
 
 	jsonData, err := json.Marshal(response)
 	if chk.E(err) {
-		http.Error(w, "Error generating response", http.StatusInternalServerError)
+		http.Error(
+			w, "Error generating response", http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -1002,7 +1149,9 @@ func (s *Server) handleACLMode(w http.ResponseWriter, r *http.Request) {
 
 	jsonData, err := json.Marshal(response)
 	if chk.E(err) {
-		http.Error(w, "Error generating response", http.StatusInternalServerError)
+		http.Error(
+			w, "Error generating response", http.StatusInternalServerError,
+		)
 		return
 	}
 
@@ -1012,7 +1161,9 @@ func (s *Server) handleACLMode(w http.ResponseWriter, r *http.Request) {
 // handleSyncCurrent handles requests for the current serial number
 func (s *Server) handleSyncCurrent(w http.ResponseWriter, r *http.Request) {
 	if s.syncManager == nil {
-		http.Error(w, "Sync manager not initialized", http.StatusServiceUnavailable)
+		http.Error(
+			w, "Sync manager not initialized", http.StatusServiceUnavailable,
+		)
 		return
 	}
 
@@ -1027,7 +1178,9 @@ func (s *Server) handleSyncCurrent(w http.ResponseWriter, r *http.Request) {
 // handleSyncEventIDs handles requests for event IDs with their serial numbers
 func (s *Server) handleSyncEventIDs(w http.ResponseWriter, r *http.Request) {
 	if s.syncManager == nil {
-		http.Error(w, "Sync manager not initialized", http.StatusServiceUnavailable)
+		http.Error(
+			w, "Sync manager not initialized", http.StatusServiceUnavailable,
+		)
 		return
 	}
 
@@ -1040,12 +1193,16 @@ func (s *Server) handleSyncEventIDs(w http.ResponseWriter, r *http.Request) {
 }
 
 // validatePeerRequest validates NIP-98 authentication and checks if the requesting peer is authorized
-func (s *Server) validatePeerRequest(w http.ResponseWriter, r *http.Request) bool {
+func (s *Server) validatePeerRequest(
+	w http.ResponseWriter, r *http.Request,
+) bool {
 	// Validate NIP-98 authentication
 	valid, pubkey, err := httpauth.CheckAuth(r)
 	if err != nil {
 		log.Printf("NIP-98 auth validation error: %v", err)
-		http.Error(w, "Authentication validation failed", http.StatusUnauthorized)
+		http.Error(
+			w, "Authentication validation failed", http.StatusUnauthorized,
+		)
 		return false
 	}
 	if !valid {
@@ -1096,3 +1253,250 @@ func (s *Server) updatePeerAdminACL(peerPubkey []byte) {
 		}
 	}
 }
+
+// =============================================================================
+// Event Service Initialization
+// =============================================================================
+
+// InitEventServices initializes the domain services for event handling.
+// This should be called after the Server is created but before accepting connections.
+func (s *Server) InitEventServices() {
+	// Initialize validation service
+	s.eventValidator = validation.NewWithConfig(&validation.Config{
+		MaxFutureSeconds: 3600, // 1 hour
+	})
+
+	// Initialize authorization service
+	authCfg := &authorization.Config{
+		AuthRequired: s.Config.AuthRequired,
+		AuthToWrite:  s.Config.AuthToWrite,
+		Admins:       s.Admins,
+		Owners:       s.Owners,
+	}
+	s.eventAuthorizer = authorization.New(
+		authCfg,
+		s.wrapAuthACLRegistry(),
+		s.wrapAuthPolicyManager(),
+		s.wrapAuthSyncManager(),
+	)
+
+	// Initialize router with handlers for special event kinds
+	s.eventRouter = routing.New()
+
+	// Register ephemeral event handler (kinds 20000-29999)
+	s.eventRouter.RegisterKindCheck(
+		"ephemeral",
+		routing.IsEphemeral,
+		routing.MakeEphemeralHandler(s.publishers),
+	)
+
+	// Initialize processing service
+	procCfg := &processing.Config{
+		Admins:       s.Admins,
+		Owners:       s.Owners,
+		WriteTimeout: 30 * time.Second,
+	}
+	s.eventProcessor = processing.New(procCfg, s.wrapDB(), s.publishers)
+
+	// Wire up optional dependencies to processing service
+	if s.rateLimiter != nil {
+		s.eventProcessor.SetRateLimiter(s.wrapRateLimiter())
+	}
+	if s.syncManager != nil {
+		s.eventProcessor.SetSyncManager(s.wrapSyncManager())
+	}
+	if s.relayGroupMgr != nil {
+		s.eventProcessor.SetRelayGroupManager(s.wrapRelayGroupManager())
+	}
+	if s.clusterManager != nil {
+		s.eventProcessor.SetClusterManager(s.wrapClusterManager())
+	}
+	s.eventProcessor.SetACLRegistry(s.wrapACLRegistry())
+}
+
+// Database wrapper for processing.Database interface
+type processingDBWrapper struct {
+	db database.Database
+}
+
+func (s *Server) wrapDB() processing.Database {
+	return &processingDBWrapper{db: s.DB}
+}
+
+func (w *processingDBWrapper) SaveEvent(ctx context.Context, ev *event.E) (exists bool, err error) {
+	return w.db.SaveEvent(ctx, ev)
+}
+
+func (w *processingDBWrapper) CheckForDeleted(ev *event.E, adminOwners [][]byte) error {
+	return w.db.CheckForDeleted(ev, adminOwners)
+}
+
+// RateLimiter wrapper for processing.RateLimiter interface
+type processingRateLimiterWrapper struct {
+	rl *ratelimit.Limiter
+}
+
+func (s *Server) wrapRateLimiter() processing.RateLimiter {
+	return &processingRateLimiterWrapper{rl: s.rateLimiter}
+}
+
+func (w *processingRateLimiterWrapper) IsEnabled() bool {
+	return w.rl.IsEnabled()
+}
+
+func (w *processingRateLimiterWrapper) Wait(ctx context.Context, opType int) error {
+	w.rl.Wait(ctx, opType)
+	return nil
+}
+
+// SyncManager wrapper for processing.SyncManager interface
+type processingSyncManagerWrapper struct {
+	sm *dsync.Manager
+}
+
+func (s *Server) wrapSyncManager() processing.SyncManager {
+	return &processingSyncManagerWrapper{sm: s.syncManager}
+}
+
+func (w *processingSyncManagerWrapper) UpdateSerial() {
+	w.sm.UpdateSerial()
+}
+
+// RelayGroupManager wrapper for processing.RelayGroupManager interface
+type processingRelayGroupManagerWrapper struct {
+	rgm *dsync.RelayGroupManager
+}
+
+func (s *Server) wrapRelayGroupManager() processing.RelayGroupManager {
+	return &processingRelayGroupManagerWrapper{rgm: s.relayGroupMgr}
+}
+
+func (w *processingRelayGroupManagerWrapper) ValidateRelayGroupEvent(ev *event.E) error {
+	return w.rgm.ValidateRelayGroupEvent(ev)
+}
+
+func (w *processingRelayGroupManagerWrapper) HandleRelayGroupEvent(ev *event.E, syncMgr any) {
+	if sm, ok := syncMgr.(*dsync.Manager); ok {
+		w.rgm.HandleRelayGroupEvent(ev, sm)
+	}
+}
+
+// ClusterManager wrapper for processing.ClusterManager interface
+type processingClusterManagerWrapper struct {
+	cm *dsync.ClusterManager
+}
+
+func (s *Server) wrapClusterManager() processing.ClusterManager {
+	return &processingClusterManagerWrapper{cm: s.clusterManager}
+}
+
+func (w *processingClusterManagerWrapper) HandleMembershipEvent(ev *event.E) error {
+	return w.cm.HandleMembershipEvent(ev)
+}
+
+// ACLRegistry wrapper for processing.ACLRegistry interface
+type processingACLRegistryWrapper struct{}
+
+func (s *Server) wrapACLRegistry() processing.ACLRegistry {
+	return &processingACLRegistryWrapper{}
+}
+
+func (w *processingACLRegistryWrapper) Configure(cfg ...any) error {
+	return acl.Registry.Configure(cfg...)
+}
+
+func (w *processingACLRegistryWrapper) Active() string {
+	return acl.Registry.Active.Load()
+}
+
+// =============================================================================
+// Authorization Service Wrappers
+// =============================================================================
+
+// ACLRegistry wrapper for authorization.ACLRegistry interface
+type authACLRegistryWrapper struct{}
+
+func (s *Server) wrapAuthACLRegistry() authorization.ACLRegistry {
+	return &authACLRegistryWrapper{}
+}
+
+func (w *authACLRegistryWrapper) GetAccessLevel(pub []byte, address string) string {
+	return acl.Registry.GetAccessLevel(pub, address)
+}
+
+func (w *authACLRegistryWrapper) CheckPolicy(ev *event.E) (bool, error) {
+	return acl.Registry.CheckPolicy(ev)
+}
+
+func (w *authACLRegistryWrapper) Active() string {
+	return acl.Registry.Active.Load()
+}
+
+// PolicyManager wrapper for authorization.PolicyManager interface
+type authPolicyManagerWrapper struct {
+	pm *policy.P
+}
+
+func (s *Server) wrapAuthPolicyManager() authorization.PolicyManager {
+	if s.policyManager == nil {
+		return nil
+	}
+	return &authPolicyManagerWrapper{pm: s.policyManager}
+}
+
+func (w *authPolicyManagerWrapper) IsEnabled() bool {
+	return w.pm.IsEnabled()
+}
+
+func (w *authPolicyManagerWrapper) CheckPolicy(action string, ev *event.E, pubkey []byte, remote string) (bool, error) {
+	return w.pm.CheckPolicy(action, ev, pubkey, remote)
+}
+
+// SyncManager wrapper for authorization.SyncManager interface
+type authSyncManagerWrapper struct {
+	sm *dsync.Manager
+}
+
+func (s *Server) wrapAuthSyncManager() authorization.SyncManager {
+	if s.syncManager == nil {
+		return nil
+	}
+	return &authSyncManagerWrapper{sm: s.syncManager}
+}
+
+func (w *authSyncManagerWrapper) GetPeers() []string {
+	return w.sm.GetPeers()
+}
+
+func (w *authSyncManagerWrapper) IsAuthorizedPeer(url, pubkey string) bool {
+	return w.sm.IsAuthorizedPeer(url, pubkey)
+}
+
+// =============================================================================
+// Message Processing Pause/Resume for Policy and Follow List Updates
+// =============================================================================
+
+// PauseMessageProcessing acquires an exclusive lock to pause all message processing.
+// This should be called before updating policy configuration or follow lists.
+// Call ResumeMessageProcessing to release the lock after updates are complete.
+func (s *Server) PauseMessageProcessing() {
+	s.messagePauseMutex.Lock()
+}
+
+// ResumeMessageProcessing releases the exclusive lock to resume message processing.
+// This should be called after policy configuration or follow list updates are complete.
+func (s *Server) ResumeMessageProcessing() {
+	s.messagePauseMutex.Unlock()
+}
+
+// AcquireMessageProcessingLock acquires a read lock for normal message processing.
+// This allows concurrent message processing while blocking during policy updates.
+// Call ReleaseMessageProcessingLock when message processing is complete.
+func (s *Server) AcquireMessageProcessingLock() {
+	s.messagePauseMutex.RLock()
+}
+
+// ReleaseMessageProcessingLock releases the read lock after message processing.
+func (s *Server) ReleaseMessageProcessingLock() {
+	s.messagePauseMutex.RUnlock()
+}

app/sprocket.go

@@ -16,7 +16,7 @@ import (
 	"github.com/adrg/xdg"
 	"lol.mleku.dev/chk"
 	"lol.mleku.dev/log"
-	"next.orly.dev/pkg/encoders/event"
+	"git.mleku.dev/mleku/nostr/encoders/event"
 )
 
 // SprocketResponse represents a response from the sprocket script

app/subscription_stability_test.go

@@ -1,328 +0,0 @@
-package app
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/gorilla/websocket"
-	"next.orly.dev/pkg/encoders/event"
-)
-
-// TestLongRunningSubscriptionStability verifies that subscriptions remain active
-// for extended periods and correctly receive real-time events without dropping.
-func TestLongRunningSubscriptionStability(t *testing.T) {
-	// Create test server
-	server, cleanup := setupTestServer(t)
-	defer cleanup()
-
-	// Start HTTP test server
-	httpServer := httptest.NewServer(server)
-	defer httpServer.Close()
-
-	// Convert HTTP URL to WebSocket URL
-	wsURL := strings.Replace(httpServer.URL, "http://", "ws://", 1)
-
-	// Connect WebSocket client
-	conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
-	if err != nil {
-		t.Fatalf("Failed to connect WebSocket: %v", err)
-	}
-	defer conn.Close()
-
-	// Subscribe to kind 1 events
-	subID := "test-long-running"
-	reqMsg := fmt.Sprintf(`["REQ","%s",{"kinds":[1]}]`, subID)
-	if err := conn.WriteMessage(websocket.TextMessage, []byte(reqMsg)); err != nil {
-		t.Fatalf("Failed to send REQ: %v", err)
-	}
-
-	// Read until EOSE
-	gotEOSE := false
-	for !gotEOSE {
-		_, msg, err := conn.ReadMessage()
-		if err != nil {
-			t.Fatalf("Failed to read message: %v", err)
-		}
-		if strings.Contains(string(msg), `"EOSE"`) && strings.Contains(string(msg), subID) {
-			gotEOSE = true
-			t.Logf("Received EOSE for subscription %s", subID)
-		}
-	}
-
-	// Set up event counter
-	var receivedCount atomic.Int64
-	var mu sync.Mutex
-	receivedEvents := make(map[string]bool)
-
-	// Start goroutine to read events
-	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
-	defer cancel()
-
-	readDone := make(chan struct{})
-	go func() {
-		defer close(readDone)
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			default:
-			}
-
-			conn.SetReadDeadline(time.Now().Add(5 * time.Second))
-			_, msg, err := conn.ReadMessage()
-			if err != nil {
-				if websocket.IsCloseError(err, websocket.CloseNormalClosure) {
-					return
-				}
-				if strings.Contains(err.Error(), "timeout") {
-					continue
-				}
-				t.Logf("Read error: %v", err)
-				return
-			}
-
-			// Parse message to check if it's an EVENT for our subscription
-			var envelope []interface{}
-			if err := json.Unmarshal(msg, &envelope); err != nil {
-				continue
-			}
-
-			if len(envelope) >= 3 && envelope[0] == "EVENT" && envelope[1] == subID {
-				// Extract event ID
-				eventMap, ok := envelope[2].(map[string]interface{})
-				if !ok {
-					continue
-				}
-				eventID, ok := eventMap["id"].(string)
-				if !ok {
-					continue
-				}
-
-				mu.Lock()
-				if !receivedEvents[eventID] {
-					receivedEvents[eventID] = true
-					receivedCount.Add(1)
-					t.Logf("Received event %s (total: %d)", eventID[:8], receivedCount.Load())
-				}
-				mu.Unlock()
-			}
-		}
-	}()
-
-	// Publish events at regular intervals over 30 seconds
-	const numEvents = 30
-	const publishInterval = 1 * time.Second
-
-	publishCtx, publishCancel := context.WithTimeout(context.Background(), 35*time.Second)
-	defer publishCancel()
-
-	for i := 0; i < numEvents; i++ {
-		select {
-		case <-publishCtx.Done():
-			t.Fatalf("Publish timeout exceeded")
-		default:
-		}
-
-		// Create test event
-		ev := &event.E{
-			Kind:      1,
-			Content:   []byte(fmt.Sprintf("Test event %d for long-running subscription", i)),
-			CreatedAt: uint64(time.Now().Unix()),
-		}
-
-		// Save event to database (this will trigger publisher)
-		if err := server.D.SaveEvent(context.Background(), ev); err != nil {
-			t.Errorf("Failed to save event %d: %v", i, err)
-			continue
-		}
-
-		t.Logf("Published event %d", i)
-
-		// Wait before next publish
-		if i < numEvents-1 {
-			time.Sleep(publishInterval)
-		}
-	}
-
-	// Wait a bit more for all events to be delivered
-	time.Sleep(3 * time.Second)
-
-	// Cancel context and wait for reader to finish
-	cancel()
-	<-readDone
-
-	// Check results
-	received := receivedCount.Load()
-	t.Logf("Test complete: published %d events, received %d events", numEvents, received)
-
-	// We should receive at least 90% of events (allowing for some timing edge cases)
-	minExpected := int64(float64(numEvents) * 0.9)
-	if received < minExpected {
-		t.Errorf("Subscription stability issue: expected at least %d events, got %d", minExpected, received)
-	}
-
-	// Close subscription
-	closeMsg := fmt.Sprintf(`["CLOSE","%s"]`, subID)
-	if err := conn.WriteMessage(websocket.TextMessage, []byte(closeMsg)); err != nil {
-		t.Errorf("Failed to send CLOSE: %v", err)
-	}
-
-	t.Logf("Long-running subscription test PASSED: %d/%d events delivered", received, numEvents)
-}
-
-// TestMultipleConcurrentSubscriptions verifies that multiple subscriptions
-// can coexist on the same connection without interfering with each other.
-func TestMultipleConcurrentSubscriptions(t *testing.T) {
-	// Create test server
-	server, cleanup := setupTestServer(t)
-	defer cleanup()
-
-	// Start HTTP test server
-	httpServer := httptest.NewServer(server)
-	defer httpServer.Close()
-
-	// Convert HTTP URL to WebSocket URL
-	wsURL := strings.Replace(httpServer.URL, "http://", "ws://", 1)
-
-	// Connect WebSocket client
-	conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
-	if err != nil {
-		t.Fatalf("Failed to connect WebSocket: %v", err)
-	}
-	defer conn.Close()
-
-	// Create 3 subscriptions for different kinds
-	subscriptions := []struct {
-		id   string
-		kind int
-	}{
-		{"sub1", 1},
-		{"sub2", 3},
-		{"sub3", 7},
-	}
-
-	// Subscribe to all
-	for _, sub := range subscriptions {
-		reqMsg := fmt.Sprintf(`["REQ","%s",{"kinds":[%d]}]`, sub.id, sub.kind)
-		if err := conn.WriteMessage(websocket.TextMessage, []byte(reqMsg)); err != nil {
-			t.Fatalf("Failed to send REQ for %s: %v", sub.id, err)
-		}
-	}
-
-	// Read until we get EOSE for all subscriptions
-	eoseCount := 0
-	for eoseCount < len(subscriptions) {
-		_, msg, err := conn.ReadMessage()
-		if err != nil {
-			t.Fatalf("Failed to read message: %v", err)
-		}
-		if strings.Contains(string(msg), `"EOSE"`) {
-			eoseCount++
-			t.Logf("Received EOSE %d/%d", eoseCount, len(subscriptions))
-		}
-	}
-
-	// Track received events per subscription
-	var mu sync.Mutex
-	receivedByKind := make(map[int]int)
-
-	// Start reader goroutine
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	readDone := make(chan struct{})
-	go func() {
-		defer close(readDone)
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			default:
-			}
-
-			conn.SetReadDeadline(time.Now().Add(2 * time.Second))
-			_, msg, err := conn.ReadMessage()
-			if err != nil {
-				if strings.Contains(err.Error(), "timeout") {
-					continue
-				}
-				return
-			}
-
-			// Parse message
-			var envelope []interface{}
-			if err := json.Unmarshal(msg, &envelope); err != nil {
-				continue
-			}
-
-			if len(envelope) >= 3 && envelope[0] == "EVENT" {
-				eventMap, ok := envelope[2].(map[string]interface{})
-				if !ok {
-					continue
-				}
-				kindFloat, ok := eventMap["kind"].(float64)
-				if !ok {
-					continue
-				}
-				kind := int(kindFloat)
-
-				mu.Lock()
-				receivedByKind[kind]++
-				t.Logf("Received event for kind %d (count: %d)", kind, receivedByKind[kind])
-				mu.Unlock()
-			}
-		}
-	}()
-
-	// Publish events for each kind
-	for _, sub := range subscriptions {
-		for i := 0; i < 5; i++ {
-			ev := &event.E{
-				Kind:      uint16(sub.kind),
-				Content:   []byte(fmt.Sprintf("Test for kind %d event %d", sub.kind, i)),
-				CreatedAt: uint64(time.Now().Unix()),
-			}
-
-			if err := server.D.SaveEvent(context.Background(), ev); err != nil {
-				t.Errorf("Failed to save event: %v", err)
-			}
-
-			time.Sleep(100 * time.Millisecond)
-		}
-	}
-
-	// Wait for events to be delivered
-	time.Sleep(2 * time.Second)
-
-	// Cancel and cleanup
-	cancel()
-	<-readDone
-
-	// Verify each subscription received its events
-	mu.Lock()
-	defer mu.Unlock()
-
-	for _, sub := range subscriptions {
-		count := receivedByKind[sub.kind]
-		if count < 4 { // Allow for some timing issues, expect at least 4/5
-			t.Errorf("Subscription %s (kind %d) only received %d/5 events", sub.id, sub.kind, count)
-		}
-	}
-
-	t.Logf("Multiple concurrent subscriptions test PASSED")
-}
-
-// setupTestServer creates a test relay server for subscription testing
-func setupTestServer(t *testing.T) (*Server, func()) {
-	// This is a simplified setup - adapt based on your actual test setup
-	// You may need to create a proper test database, etc.
-	t.Skip("Implement setupTestServer based on your existing test infrastructure")
-	return nil, func() {}
-}

app/web/.gitignore

@@ -1,5 +1,8 @@
 node_modules/
 dist/
+public/bundle.js
+public/bundle.js.map
+public/bundle.css
 .vite/
 .tanstack/
 .idea/

app/web/bun.lock

@@ -4,8 +4,9 @@
     "": {
       "name": "svelte-app",
       "dependencies": {
-        "applesauce-core": "^4.1.0",
-        "applesauce-signers": "^4.1.0",
+        "applesauce-core": "^4.4.2",
+        "applesauce-signers": "^4.2.0",
+        "hash-wasm": "^4.12.0",
         "nostr-tools": "^2.17.0",
         "sirv-cli": "^2.0.0",
       },
@@ -79,9 +80,9 @@
 
     "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="],
 
-    "applesauce-core": ["applesauce-core@4.1.0", "", { "dependencies": { "@noble/hashes": "^1.7.1", "@scure/base": "^1.2.4", "debug": "^4.4.0", "fast-deep-equal": "^3.1.3", "hash-sum": "^2.0.0", "light-bolt11-decoder": "^3.2.0", "nanoid": "^5.0.9", "nostr-tools": "~2.17", "rxjs": "^7.8.1" } }, "sha512-vFOHfqWW4DJfvPkMYLYNiy2ozO2IF+ZNwetGqaLuPjgE1Iwu4trZmG3GJUH+lO1Oq1N4e/OQ/EcotJoEBEiW7Q=="],
+    "applesauce-core": ["applesauce-core@4.4.2", "", { "dependencies": { "@noble/hashes": "^1.7.1", "@scure/base": "^1.2.4", "debug": "^4.4.0", "fast-deep-equal": "^3.1.3", "hash-sum": "^2.0.0", "light-bolt11-decoder": "^3.2.0", "nanoid": "^5.0.9", "nostr-tools": "~2.17", "rxjs": "^7.8.1" } }, "sha512-zuZB74Pp28UGM4e8DWbN1atR95xL7ODENvjkaGGnvAjIKvfdgMznU7m9gLxr/Hu+IHOmVbbd4YxwNmKBzCWhHQ=="],
 
-    "applesauce-signers": ["applesauce-signers@4.1.0", "", { "dependencies": { "@noble/hashes": "^1.7.1", "@noble/secp256k1": "^1.7.1", "@scure/base": "^1.2.4", "applesauce-core": "^4.1.0", "debug": "^4.4.0", "nanoid": "^5.0.9", "nostr-tools": "~2.17", "rxjs": "^7.8.2" } }, "sha512-S+nTkAt1CAGhalwI7warLTINsxxjBpS3NqbViz6LVy1ZrzEqaNirlalX+rbCjxjRrvIGhYV+rszkxDFhCYbPkg=="],
+    "applesauce-signers": ["applesauce-signers@4.2.0", "", { "dependencies": { "@noble/hashes": "^1.7.1", "@noble/secp256k1": "^1.7.1", "@scure/base": "^1.2.4", "applesauce-core": "^4.2.0", "debug": "^4.4.0", "nanoid": "^5.0.9", "nostr-tools": "~2.17", "rxjs": "^7.8.2" } }, "sha512-celexNd+aLt6/vhf72XXw2oAk8ohjna+aWEg/Z2liqPwP+kbVjnqq4Z1RXvt79QQbTIQbXYGWqervXWLE8HmHg=="],
 
     "array-union": ["array-union@2.1.0", "", {}, "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw=="],
 
@@ -143,6 +144,8 @@
 
     "hash-sum": ["hash-sum@2.0.0", "", {}, "sha512-WdZTbAByD+pHfl/g9QSsBIIwy8IT+EsPiKDs0KNX+zSHhdDLFKdZu0BQHljvO+0QI/BasbMSUa8wYNCZTvhslg=="],
 
+    "hash-wasm": ["hash-wasm@4.12.0", "", {}, "sha512-+/2B2rYLb48I/evdOIhP+K/DD2ca2fgBjp6O+GBEnCDk2e4rpeXIK8GvIyRPjTezgmWn9gmKwkQjjx6BtqDHVQ=="],
+
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
     "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],

app/web/dist/index.html

@@ -3,10 +3,32 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
 
     <title>ORLY?</title>
 
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+      html, body {
+        background-color: #fff;
+        color: #000;
+      }
+      @media (prefers-color-scheme: dark) {
+        html, body {
+          background-color: #000;
+          color: #fff;
+        }
+      }
+    </style>
+
     <link rel="icon" type="image/png" href="/favicon.png" />
+    <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icon-192.png" />
+    <meta name="theme-color" content="#000000" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black" />
     <link rel="stylesheet" href="/global.css" />
     <link rel="stylesheet" href="/bundle.css" />
 
@@ -14,4 +36,9 @@
   </head>
 
   <body></body>
+  <script>
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.register('/sw.js');
+    }
+  </script>
 </html>

app/web/package-lock.json

@@ -8,9 +8,11 @@
       "name": "svelte-app",
       "version": "1.0.0",
       "dependencies": {
-        "applesauce-core": "^4.1.0",
-        "applesauce-signers": "^4.1.0",
+        "applesauce-core": "^4.4.2",
+        "applesauce-signers": "^4.2.0",
+        "hash-wasm": "^4.12.0",
         "nostr-tools": "^2.17.0",
+        "qrcode": "^1.5.3",
         "sirv-cli": "^2.0.0"
       },
       "devDependencies": {
@@ -365,6 +367,30 @@
         "node": ">=0.4.0"
       }
     },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/anymatch": {
       "version": "3.1.3",
       "dev": true,
@@ -389,9 +415,9 @@
       }
     },
     "node_modules/applesauce-core": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/applesauce-core/-/applesauce-core-4.1.0.tgz",
-      "integrity": "sha512-vFOHfqWW4DJfvPkMYLYNiy2ozO2IF+ZNwetGqaLuPjgE1Iwu4trZmG3GJUH+lO1Oq1N4e/OQ/EcotJoEBEiW7Q==",
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/applesauce-core/-/applesauce-core-4.4.2.tgz",
+      "integrity": "sha512-zuZB74Pp28UGM4e8DWbN1atR95xL7ODENvjkaGGnvAjIKvfdgMznU7m9gLxr/Hu+IHOmVbbd4YxwNmKBzCWhHQ==",
       "license": "MIT",
       "dependencies": {
         "@noble/hashes": "^1.7.1",
@@ -431,15 +457,15 @@
       }
     },
     "node_modules/applesauce-signers": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/applesauce-signers/-/applesauce-signers-4.1.0.tgz",
-      "integrity": "sha512-S+nTkAt1CAGhalwI7warLTINsxxjBpS3NqbViz6LVy1ZrzEqaNirlalX+rbCjxjRrvIGhYV+rszkxDFhCYbPkg==",
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/applesauce-signers/-/applesauce-signers-4.2.0.tgz",
+      "integrity": "sha512-celexNd+aLt6/vhf72XXw2oAk8ohjna+aWEg/Z2liqPwP+kbVjnqq4Z1RXvt79QQbTIQbXYGWqervXWLE8HmHg==",
       "license": "MIT",
       "dependencies": {
         "@noble/hashes": "^1.7.1",
         "@noble/secp256k1": "^1.7.1",
         "@scure/base": "^1.2.4",
-        "applesauce-core": "^4.1.0",
+        "applesauce-core": "^4.2.0",
         "debug": "^4.4.0",
         "nanoid": "^5.0.9",
         "nostr-tools": "~2.17",
@@ -533,6 +559,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/camelcase": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz",
+      "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/chokidar": {
       "version": "3.6.0",
       "dev": true,
@@ -556,6 +591,35 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/cliui": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz",
+      "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.0",
+        "wrap-ansi": "^6.2.0"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
     "node_modules/colorette": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/colorette/-/colorette-1.4.0.tgz",
@@ -604,6 +668,15 @@
         }
       }
     },
+    "node_modules/decamelize": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz",
+      "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/deepmerge": {
       "version": "4.3.1",
       "dev": true,
@@ -612,6 +685,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/dijkstrajs": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/dijkstrajs/-/dijkstrajs-1.0.3.tgz",
+      "integrity": "sha512-qiSlmBq9+BCdCA/L46dw8Uy93mloxsPSbwnm5yrKn2vMPiy8KyAskTF6zuV/j5BMsmOGZDPs7KjU+mjb670kfA==",
+      "license": "MIT"
+    },
     "node_modules/dir-glob": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz",
@@ -625,6 +704,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
     "node_modules/estree-walker": {
       "version": "2.0.2",
       "dev": true,
@@ -674,6 +759,19 @@
         "node": ">=8"
       }
     },
+    "node_modules/find-up": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz",
+      "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
+      "license": "MIT",
+      "dependencies": {
+        "locate-path": "^5.0.0",
+        "path-exists": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/fs-extra": {
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
@@ -702,6 +800,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
     "node_modules/get-port": {
       "version": "3.2.0",
       "license": "MIT",
@@ -817,6 +924,12 @@
       "integrity": "sha512-WdZTbAByD+pHfl/g9QSsBIIwy8IT+EsPiKDs0KNX+zSHhdDLFKdZu0BQHljvO+0QI/BasbMSUa8wYNCZTvhslg==",
       "license": "MIT"
     },
+    "node_modules/hash-wasm": {
+      "version": "4.12.0",
+      "resolved": "https://registry.npmjs.org/hash-wasm/-/hash-wasm-4.12.0.tgz",
+      "integrity": "sha512-+/2B2rYLb48I/evdOIhP+K/DD2ca2fgBjp6O+GBEnCDk2e4rpeXIK8GvIyRPjTezgmWn9gmKwkQjjx6BtqDHVQ==",
+      "license": "MIT"
+    },
     "node_modules/hasown": {
       "version": "2.0.2",
       "dev": true,
@@ -885,6 +998,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-glob": {
       "version": "4.0.3",
       "dev": true,
@@ -982,6 +1104,18 @@
         "node": ">=6"
       }
     },
+    "node_modules/locate-path": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
+      "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
+      "license": "MIT",
+      "dependencies": {
+        "p-locate": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.27.0",
       "dev": true,
@@ -1127,6 +1261,51 @@
       "dev": true,
       "license": "BSD-2-Clause"
     },
+    "node_modules/p-limit": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
+      "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
+      "license": "MIT",
+      "dependencies": {
+        "p-try": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-locate": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz",
+      "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
+      "license": "MIT",
+      "dependencies": {
+        "p-limit": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/p-try": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz",
+      "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/path-exists": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
+      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/path-is-absolute": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
@@ -1163,6 +1342,32 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/pngjs": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-5.0.0.tgz",
+      "integrity": "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
+    "node_modules/qrcode": {
+      "version": "1.5.4",
+      "resolved": "https://registry.npmjs.org/qrcode/-/qrcode-1.5.4.tgz",
+      "integrity": "sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==",
+      "license": "MIT",
+      "dependencies": {
+        "dijkstrajs": "^1.0.1",
+        "pngjs": "^5.0.0",
+        "yargs": "^15.3.1"
+      },
+      "bin": {
+        "qrcode": "bin/qrcode"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -1214,6 +1419,21 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/require-main-filename": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz",
+      "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==",
+      "license": "ISC"
+    },
     "node_modules/resolve": {
       "version": "1.22.10",
       "dev": true,
@@ -1425,6 +1645,12 @@
         "randombytes": "^2.1.0"
       }
     },
+    "node_modules/set-blocking": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
+      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
+      "license": "ISC"
+    },
     "node_modules/sirv": {
       "version": "2.0.4",
       "license": "MIT",
@@ -1489,6 +1715,32 @@
         "source-map": "^0.6.0"
       }
     },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/supports-preserve-symlinks-flag": {
       "version": "1.0.0",
       "dev": true,
@@ -1573,6 +1825,26 @@
         "node": ">= 4.0.0"
       }
     },
+    "node_modules/which-module": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz",
+      "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==",
+      "license": "ISC"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
+      "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/wrappy": {
       "version": "1.0.2",
       "dev": true,
@@ -1597,6 +1869,47 @@
           "optional": true
         }
       }
+    },
+    "node_modules/y18n": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz",
+      "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==",
+      "license": "ISC"
+    },
+    "node_modules/yargs": {
+      "version": "15.4.1",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz",
+      "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^6.0.0",
+        "decamelize": "^1.2.0",
+        "find-up": "^4.1.0",
+        "get-caller-file": "^2.0.1",
+        "require-directory": "^2.1.1",
+        "require-main-filename": "^2.0.0",
+        "set-blocking": "^2.0.0",
+        "string-width": "^4.2.0",
+        "which-module": "^2.0.0",
+        "y18n": "^4.0.0",
+        "yargs-parser": "^18.1.2"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "18.1.3",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz",
+      "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==",
+      "license": "ISC",
+      "dependencies": {
+        "camelcase": "^5.0.0",
+        "decamelize": "^1.2.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
     }
   }
 }

app/web/package.json

@@ -4,9 +4,11 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "fetch-kinds": "node scripts/fetch-kinds.js",
+    "prebuild": "npm run fetch-kinds",
     "build": "rollup -c",
     "dev": "rollup -c -w",
-    "start": "sirv public --no-clear"
+    "start": "sirv public --no-clear --single"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^24.0.0",
@@ -20,9 +22,11 @@
     "svelte": "^3.55.0"
   },
   "dependencies": {
-    "applesauce-core": "^4.1.0",
-    "applesauce-signers": "^4.1.0",
+    "applesauce-core": "^4.4.2",
+    "applesauce-signers": "^4.2.0",
+    "hash-wasm": "^4.12.0",
     "nostr-tools": "^2.17.0",
+    "qrcode": "^1.5.3",
     "sirv-cli": "^2.0.0"
   }
 }

app/web/public/index.html

@@ -3,10 +3,32 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
 
     <title>ORLY?</title>
 
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+      html, body {
+        background-color: #fff;
+        color: #000;
+      }
+      @media (prefers-color-scheme: dark) {
+        html, body {
+          background-color: #000;
+          color: #fff;
+        }
+      }
+    </style>
+
     <link rel="icon" type="image/png" href="/favicon.png" />
+    <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icon-192.png" />
+    <meta name="theme-color" content="#000000" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black" />
     <link rel="stylesheet" href="/global.css" />
     <link rel="stylesheet" href="/bundle.css" />
 
@@ -14,4 +36,9 @@
   </head>
 
   <body></body>
+  <script>
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.register('/sw.js');
+    }
+  </script>
 </html>

app/web/public/manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "ORLY Nostr Relay",
+  "short_name": "ORLY",
+  "description": "High-performance Nostr relay",
+  "display": "standalone",
+  "start_url": "/",
+  "scope": "/",
+  "theme_color": "#000000",
+  "background_color": "#000000",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ]
+}