| name | naan-archiver |
| description | Decentralized web archiving on Nostr + Blossom. Archive URLs (web pages, videos, documents) to content-addressed Blossom storage and index them as kind 4554 events on Nostr with OpenTimestamps proofs. Use when: (1) archiving a URL or web page, (2) looking up existing archives of a URL, (3) uploading files to Blossom, (4) upgrading pending OpenTimestamps proofs, (5) monitoring Nostr mentions for archive requests, (6) setting up a new NAAN archival node. Triggers on: archive, blossom, kind 4554, web archive, preserve, snapshot, wayback, OTS, OpenTimestamps. |
NAAN Archiver
Turn any OpenClaw agent into a Nostr Agentic Archiving Node. Archives web content to Blossom (content-addressed blob storage) and indexes it on Nostr via kind 4554 events, with optional Bitcoin-anchored timestamps via OpenTimestamps.
Setup
1. Configuration
Create naan.conf in the workspace root:
NSEC_FILE="/path/to/.nostr-nsec.key"
OPERATOR_PUBKEY=""
OWNER_PUBKEY=""
ACCESS_TIER="follows"
WHITELIST_FILE=""
BLACKLIST_FILE=""
BLOSSOM_SERVERS="https://blossom.primal.net https://cdn.hzrd149.com"
RELAYS="wss://relay.damus.io wss://relay.primal.net wss://nos.lol"
ARCHIVE_DIR="./archives"
CHROME_PATH="/usr/bin/chromium"
If OPERATOR_PUBKEY is set, the skill queries relays for:
- Kind 10063 (Blossom server list) to discover upload targets
- Kind 10002 (NIP-65 relay list) to discover publish relays
- Kind 3 (contacts) for WoT-gated access control
Falls back to BLOSSOM_SERVERS and RELAYS if discovery returns nothing.
2. Dependencies
Required: nak, curl, jq, sha256sum
Web archiving: single-file-cli + Chromium
Video archiving: yt-dlp
Timestamping: ots (github.com/fiatjaf/ots)
Commands
Archive a URL
bash scripts/archive-url.sh <url> [--video] [--requester <pubkey>] [--dry-run]
Full pipeline: download content, compute SHA-256, upload to Blossom servers, publish kind 4554 event, submit to OpenTimestamps. Auto-detects video URLs (YouTube, Vimeo, Twitter/X, TikTok, Rumble).
Look up existing archives
bash scripts/lookup-archive.sh <url>
Queries relays for kind 4554 events matching the URL. Use before archiving to avoid duplicates.
Upload a file to Blossom
bash scripts/blossom-upload.sh <file> [blossom_server_url]
Uploads with NIP-98 (kind 24242) authorization. Returns JSON with url, sha256, size.
Stamp a Nostr event with OpenTimestamps
bash scripts/ots-stamp.sh <event_id>
Upgrade pending OTS proofs
bash scripts/ots-upgrade.sh [--publish]
Scans for pending .ots files, upgrades them when Bitcoin attestation is available, and (with --publish) publishes kind 1040 events.
Monitor mentions for archive requests
bash scripts/monitor-mentions.sh [--dry-run] [--since <unix_ts>]
Queries kind 1 events tagging the node's pubkey, filters by WoT (owner's follow list), extracts URLs, archives them, replies publicly. Rate limited to 3 archives per run, ignores mentions older than 10 minutes.
Event Spec
See references/event-spec.md for the full kind 4554 archive event schema and kind 1040 OTS proof format.
Access Control
Configure ACCESS_TIER in naan.conf to control who can request archives:
| Tier | Who can request |
|---|
owner | Only the owner pubkey |
friends | Mutual follows (owner follows them AND they follow the owner) |
followers | Anyone who follows the owner |
follows | Anyone the owner follows (default) |
anyone | Open to all pubkeys (not recommended for public nodes) |
The owner is always allowed regardless of tier. Evaluation order:
- Blacklist (always deny)
- Whitelist (always allow)
- Owner (always allow)
- Access tier (evaluated per above)
Optional whitelist/blacklist files contain one hex pubkey per line:
ACCESS_TIER="follows"
WHITELIST_FILE="./whitelist.txt"
BLACKLIST_FILE="./blacklist.txt"
Deploy Archive Index
Every NAAN node can deploy its own browseable archive index as an nsite:
bash scripts/deploy-nsite.sh
This clones the NAAN site from GitHub, builds it, and deploys it to Blossom servers and Nostr relays using the node's own nsec. The site is then accessible at https://<your-npub>.nsite.lol/.
To pull the latest site code and redeploy:
bash scripts/deploy-nsite.sh --update
Requires: git, node, npm, nsyte
Periodic Tasks
Set up cron jobs for:
- OTS upgrade: run
ots-upgrade.sh --publish every 1-2 hours to finalize pending Bitcoin timestamps
- Mention monitoring: run
monitor-mentions.sh every 5-10 minutes to auto-archive from mentions
