naan-archiver

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:

# Required: path to Nostr secret key (nsec1... or hex)
NSEC_FILE="/path/to/.nostr-nsec.key"

# Optional: operator's pubkey (hex). If set, relays and Blossom servers
# are auto-discovered from kind 10002 and kind 10063 events.
OPERATOR_PUBKEY=""

# Optional: owner pubkey for access control
OWNER_PUBKEY=""

# Who can request archives: owner | friends | followers | follows | anyone
ACCESS_TIER="follows"

# Optional: always allow/deny specific pubkeys (one hex pubkey per line)
WHITELIST_FILE=""
BLACKLIST_FILE=""

# Overrides (used if auto-discovery fails or OPERATOR_PUBKEY is unset)
BLOSSOM_SERVERS="https://blossom.primal.net https://cdn.hzrd149.com"
RELAYS="wss://relay.damus.io wss://relay.primal.net wss://nos.lol"

# Archive storage
ARCHIVE_DIR="./archives"

# Chrome path for SingleFile
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:

1. Blacklist (always deny)
2. Whitelist (always allow)
3. Owner (always allow)
4. 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