---
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:

```bash
# 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
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
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
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
bash scripts/ots-stamp.sh <event_id>
```

### Upgrade pending OTS proofs

```bash
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
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:

```bash
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
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
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