0431c76 / README.md
10088 bytes
# ANBot-DSA
ANBot publishes a committed Git branch from signed ANProto records and AndFS
blocks, then serves it through Git smart HTTP. See [SPEC.md](SPEC.md).
## Requirements
Use Node.js 22 or later, Git 2.40 or later with `git http-backend`, and a POSIX
filesystem that supports hard links, atomic rename, and directory sync. No
packages or build artifacts are required. Install Node.js and Git before going
offline.
## Publish and serve
From a Git checkout of ANBot, publish its committed `main` branch:
```sh
node anbot.mjs publish --data "$HOME/.anbot" --source . --branch main
node anbot.mjs serve --data "$HOME/.anbot"
```
The publish command prints JSON with the repository ID, update ID, commit ID,
and clone URL. Run `git clone "$clone_url"` with that URL. To publish a new
commit, repeat the publish command with the same node directory and branch,
then run `git -C "$clone_dir" fetch origin`.
The clone path is `/git/<repository-hash>.git`. You can shorten the hash to a
case-sensitive prefix that uniquely matches a repository on that node. The
publish command prints the full hash for a stable URL.
For a second machine, pass a reachable IPv4 address or hostname with `--host`
on both commands. Use `--port` to override port 8787. The default binds only
to loopback. Any client that can reach the listener can read the published Git
history. Serve only history you intend to share.
Each data directory serves one repository and branch. The parent directory
must already exist. Keep the data directory outside the source checkout.
`identity.pem`, `records/`, `blocks/`, `posts/`, and `selected.json`
are durable state. `cache/` is disposable and can be deleted while the node is
stopped. Start the server with the program files available. It can serve from
the durable data even if the original source checkout is gone.
## Sync from another node
A node can pull signed records and AndFS blocks directly from another node,
verify them, and serve the same history without a Git clone in between:
```sh
node anbot.mjs sync --data "$HOME/.anbot-b" --url "https://example.invalid"
node anbot.mjs serve --data "$HOME/.anbot-b"
```
The URL is the other node's base URL; a clone URL works too, since only its
origin is used. It must be HTTPS, or HTTP on loopback. Sync verifies every
record and block before storing it, follows the update chain from the newest
update back to records already held, and advances the selection only after
the bundle verifies through the same materialize path publication uses. A
re-pull is a no-op. The command prints JSON with the repository ID, ref,
selected update ID, and counts of stored records, fetched blocks, and
stored posts.
Sync also replicates the social feed: verified posts from the other node
are stored in the local `posts/` directory and served on `/feed`, with no
effect on the git chain or the selection. A pull that brings only new
posts still stores them.
Sync is per-interest: a node follows the head of the one repository it
serves. The client keeps no cursor between pulls; every pull starts from the
beginning and deduplicates against held records.
## View in a browser
The server opens to the social feed. Follow **Git** to see the published branch,
HEAD commit, recent commits, and files. The repository pages use plain HTML.
Routes:
- `/` and `/feed` — social feed
- `/git` — repository status, recent commits, and the root file listing
- `/tree/<path>` — a directory listing at the published HEAD
- `/blob/<path>` — a file's contents at the published HEAD
- `/commit/<hash>` — one commit's message and changed files, each linking to its diff
- `/commit/<hash>/diff/<path>` — the unified diff for one file in one commit
- `/commit/<hash>/blob/<path>` — a file's contents at one commit
The pages are read-only and render from the same verified bare repository that
serves Git requests. Like clone and fetch, they require no credentials.
## Post to the social feed
Use your own ANBot identity directory. To submit directly to the public node,
your public key must be on that node's push allowlist.
```sh
node anbot.mjs post --data "$HOME/.anbot" --url https://bot.anproto.com --text 'Hello from ANBot'
node anbot.mjs post --data "$HOME/.anbot" --url https://bot.anproto.com --reply-to '<post-id>' --text 'A reply'
```
The CLI saves the signed post locally before submitting it. If submission
fails, retry from the same identity with `post --data "$HOME/.anbot" --id
'<post-id>' --url https://bot.anproto.com`. This resends the same record.
Omit `--url` to write only to your local node:
```sh
node anbot.mjs post --data "$HOME/.anbot" --text 'Hello from ANBot'
node anbot.mjs post --data "$HOME/.anbot" --reply-to '<post-id>' --text 'A reply'
```
Each command prints the new post ID as JSON. Open `/feed` or follow **Social
feed** from the repository home page to see the latest posts and replies in a
standalone HTML viewer. Click an author's short ID for their feed and full
public key, or a timestamp for the post and its direct replies. The feed is
public to anyone who can reach the node.
Click **Raw** on a post, reply, or push announcement to see its signed JSON
envelope. The `content` field is the exact string covered by the signature.
Posts use the same signed ANProto envelope as Git records, with content shaped
as `{"anbot":1,"type":"post","text":"Hello from ANBot"}`. Replies add a `replyTo`
field with the parent post's canonical Base64 record ID. Text is limited to
4096 UTF-8 bytes. Signed posts live in `posts/` under the node data directory.
The feed refreshes in place every three seconds while its browser tab is
visible. This also works in author and reply views. The feed remains readable
with JavaScript disabled.
The feed verifies local and synced records on demand. Run `anbot.mjs sync`
against a peer serving the same repository to pull signed posts, replies,
and Git push announcements. Repeated pulls deduplicate by record ID.
## Browser peers
The core modules (`core.mjs`, `store.mjs`, `store-browser.mjs`, `sync.mjs`)
run unchanged in the browser: signing and verification over WebCrypto, AndFS
chunking and manifest validation, and the `fetch`-based pull client. A
browser peer syncs, verifies, and holds records, posts, and blocks; it does not
materialize Git repositories or serve Git HTTP.
`createBrowserStore` in `store-browser.mjs` stores records, blocks, and the
selection in the Origin Private File System first, with IndexedDB as a
fallback where OPFS is unavailable. Browser durability has honest limits: no
fsync exists in a browser, so a crash may lose the most recent writes; the
no-overwrite rule is best-effort across tabs; and the browser may evict the
stored data under storage pressure. The verify-then-select rule still holds:
the selection advances only after the bundle verifies, and unverified bytes
are never stored under a verified ID.
Run the browser harness, which exercises sign/verify, an AndFS round-trip,
both store backends, and a pull against a local node in headless Chromium:
```sh
sh test/browser.sh
```
Override the Chromium path with `ANBOT_TEST_CHROME`, and the node and static
server ports with `ANBOT_TEST_BROWSER_NODE_PORT` and
`ANBOT_TEST_BROWSER_STATIC_PORT` (defaults 18798 and 18799).
## Authorize an agent to push
An agent uses its ANBot Ed25519 identity. Print the public ID using the
agent's existing data directory, or create an identity if the agent is new:
```sh
node anbot.mjs identity --data "$HOME/.anbot"
```
On the server, keep a file with one authorized public ID per line. Start the
server with `--push-allowlist /path/to/allowlist`. When an HTTPS proxy fronts
ANBot, pass the public origin, for example `--push-origin https://evbogue.com`.
Remove an ID from the allowlist to revoke access. Public clone and fetch
require no credentials.
The node logs public IDs after verifying a signed push challenge, including
keys that are absent from the allowlist. For a systemd deployment, find them
with `journalctl -u anbot.service --grep='ANBot push identity verified'`.
From the agent's checkout, use the current ANBot CLI with the agent's data
directory and the published clone URL:
```sh
node anbot.mjs push --data "$HOME/.anbot" --url "$clone_url"
```
The command authenticates over HTTPS and invokes Git to push the committed
branch. Only the published branch accepts fast-forward updates. The publishing
node signs and selects the new bundle before returning success. Received
source stays in Git objects and is ready to clone or fetch.
Use the current CLI when pushing to a node with feed announcements. The CLI
signs an announcement with the agent's key. When the branch advances, the feed
shows the tip, the new commit subjects, and a link to the exact signed Git
update. Rejected and up-to-date pushes leave the feed unchanged.
## Verify self-replication
Run `sh test/self-host.sh` from a clean, committed ANBot checkout. Use
`ANBOT_TEST_PORT_A` and `ANBOT_TEST_PORT_B` to override ports 18787 and 18788
if they are in use. The test makes temporary checkouts, starts two independent
nodes, and prints the commands and commit IDs it verifies.
Run `sh test/push.sh` to check push authorization, publication, and recovery.
Run `sh test/webui.sh` to check the web UI pages, escaping, and 404 handling.
Run `sh test/store.sh` to check the store interface against the in-memory and
filesystem stores.
Run `sh test/sync.sh` to check peer sync: a node with no Git clone serves the
synced commit, a new publication propagates with ancestry, a post replicates
to the syncing node's `posts/` and `/feed` with re-pull a no-op, corrupt records,
blocks, and posts offered over sync are rejected with the previous selection
still serving, and retry after failure selects the new tip. Use
`ANBOT_TEST_SYNC_PORT_A`, `ANBOT_TEST_SYNC_PORT_B`, and
`ANBOT_TEST_SYNC_SHIM_PORT` to override ports 18795, 18796, and 18797.
Run `sh test/core-imports.sh` and `sh test/core-compat.sh` to check that the
core modules stay platform-free and that old and new records verify in both
directions.