c1d80cc / README.md
5685 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/`, 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.
## View in a browser
Open the server's root URL in a browser to see the published repository: the
branch, HEAD commit, recent commits, and files. The repository pages use plain
HTML. Routes:
- `/` — 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
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 the data directory of the node serving the feed:
```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.
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 reads and verifies those local records on demand. Node-to-node feed
replication and following are future work.
## 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.