Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ That answers with a relay at a memorable name, open to anyone for 14 days. Claim
- **A community.** Members, invite links, an invite tree, moderators with a log of what they did, a signed roster and one NIP-29 group per relay, so group-aware clients show it as a place.
- **A site.** Notes and articles as pages with link previews, an Atom feed, and a card with a QR of the group address. NIP-5A also serves root, named and snapshot websites from signed manifests on isolated hostnames, with verified files, optional mirroring and sign-in that follows the relay's read rule.
- **Encrypted group transport.** Opt-in Marmot KeyPackages and opaque MLS group messages, with account admission and storage caps for ephemeral authors. Clients manage encryption and group membership.
- **A Git host.** Opt-in GRASP-01 Smart HTTP, backed by [ntig](https://github.com/FelineStateMachine/ntig). Signed NIP-34 state authorizes branch and tag changes; events wait for their Git objects before publication. Hosting has [explicit storage and transaction limits](docs/22-grasp-01-git-hosting.md#git-http).
- **A Git host.** Opt-in GRASP-01 Smart HTTP, backed by [ntig](https://github.com/FelineStateMachine/ntig). Signed NIP-34 state authorizes branch and tag changes; events wait for their Git objects before publication. Hosting has [explicit storage and transaction limits](docs/22-grasp-01-git-hosting.md#git-http), and the owner can request a bounded read-only inventory without authorizing deletion.
- **A file host.** Blossom and NIP-96 on the same bucket, with mirroring, pre-flight checks and file reports.
- **A console.** Nine tabs on the relay's own page, signed by a browser extension or a remote signer app on a phone. Presets set up an outbox, an inbox, a private relay, a chat, a search replica, a media host or a quiet relay with every costly feature off, in one click. The template collection also includes static sites, public or member-published Marmot transport and Git repositories.
- **A file.** Everything the console sets, as one document with a schema: check it offline, see what applying would change, apply it, pull it back. Keep your relay in your repository. The presets are the same files, in `relay-templates/`.
Expand All @@ -46,7 +46,7 @@ Site hosting and mirroring are on by default; Marmot and GRASP are off until ena

**For scripts and agents**

- [Scripts and agents](docs/13-scripts-and-agents.md): a relay end to end with a key and curl, every management method, and the relay as a configuration file.
- [Scripts and agents](docs/13-scripts-and-agents.md): a relay end to end with a key and curl, every management method including Git storage inventory, and the relay as a configuration file.
- [HTTP reference](docs/14-http-reference.md): every path, method, auth and answer.

**For developers**
Expand All @@ -55,7 +55,7 @@ Site hosting and mirroring are on by default; Marmot and GRASP are off until ena
- [Hosting bind.ws](docs/11-hosting-bindws.md): run your own on your own domain, and watch it through logs, traces and metrics.
- [Hosting without Cloudflare](docs/16-hosting-without-cloudflare.md): the same Worker on celld, with your own bucket and proxy, and what "supported" promises.
- [Develop and extend](docs/12-develop-extend.md): layout, tests, adding methods and NIPs, the console, the templates.
- [Costs and margins](docs/15-costs-and-margins.md): tenant meters, host accounting gaps, margin scenarios and the proposed maintenance budget contract.
- [Costs and margins](docs/15-costs-and-margins.md): application budgets, retained storage, inventory interpretation and deployment margins.

### Draft NIPs

Expand Down
27 changes: 27 additions & 0 deletions docs/10-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,33 @@ accepted state as its authorization boundary and passes Git objects through
the object-store seam. It stays separate from the NIP-5A site door, so a site
hostname cannot reach relay events or repository data.

`repository-access.ts` gives one live Durable Object operation the repository
authority token across awaits. Git HTTP, owner controls, alarms, event
ingestion and direct lease, adoption and teardown paths use the same admission
seam; nested work owned by the active token proceeds, while another live
operation receives a retry response. Async context carries the token, so the
fence replaces separate Git and control flags without becoming a durable lock.
Management reads and verifies the request before taking ownership, so an
incomplete unauthenticated body cannot hold the relay's admission token.
It does not coordinate a crashed instance, another R2 client or another object
using the prefix, and it never authorizes garbage collection.

`git-storage.ts` implements the owner-only `gitstorage` management method. It
walks one accepted repository's physical R2 objects within explicit budgets,
compares them with the live dependency inventory and reports physical, live,
unreferenced and unknown objects by class alongside SQL reservations and their
difference from listed bytes. An incomplete, over-budget or changed-root walk
returns an error and no partial report. The manual scan has a 60-second
per-instance cooldown and does not delete or reclaim storage.

[Tangled knots](https://docs.tangled.org/knot-self-hosting-guide) provide
useful prior art: AT Protocol identity sits above a filesystem Git host with
repository maintenance. Bindws instead publishes immutable objects through
an R2 root. The storage layout and recovery contract determine which old
objects can be reclaimed; decentralized identity does not require retaining
every superseded manifest. A collection protocol still needs to protect old
readers, unpublished writes and retained transaction receipts.

## Views

`src/views.ts` is a registry of folds. Each view names a trigger, an audience and a fold that returns tags and content; hourly views add a fingerprint so nothing is republished when the inputs did not move. The record is a kind 30078 signed by the identity key on the same strictly increasing clock as the group state, `d` = `bind.ws/view/<name>`, stored and broadcast through `emit` like the roster, taken down when the view is switched off, empty, or no longer public. The rows a run wrote are measured around the fold from the store's write counter and kept as the last 60 runs, which the console and the digest read.
Expand Down
6 changes: 6 additions & 0 deletions docs/13-scripts-and-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ await rpc("claim"); // { result: { owner, claimed: true, c
await rpc("applypreset", "outbox"); // one call sets writes, reads, kinds and keep-for
await rpc("backfill", ["wss://relay.damus.io", "wss://nos.lol"]);
console.log(await rpc("listjobs"));
console.log(await rpc("gitstorage", "<owner hex pubkey>", "my-project"));
```

The bridge takes the same header. `POST /events` answers `{ event_id, accepted, message }`; `POST /query` answers a list of events; `POST /count` answers `{ count }`. The bridge is rate limited per address at four times the per-connection allowance and answers `429` past it.
Expand Down Expand Up @@ -137,6 +138,7 @@ The bridge takes the same header. `POST /events` answers `{ event_id, accepted,
**Storage**

- `storagestats`: bytes by kind, files, retention.
- `gitstorage owner identifier`: an owner-only inventory of one accepted GRASP repository. The result compares bounded physical R2 listing with live Git dependencies and reports physical, live, unreferenced and unknown objects by class, SQL reservations and the byte difference. It never deletes data.
- `deleteblob sha256`.
- `listdumps`, `dumpnow`, `deletedump name`.

Expand Down Expand Up @@ -164,6 +166,10 @@ The bridge takes the same header. `POST /events` answers `{ event_id, accepted,

- `deleterelay name`: the relay's own name, typed, is the confirmation.

`gitstorage` is a diagnostic read, not a billing ledger or a deletion grant.
Its operation counts do not add a tenant charge, and its 60-second cooldown is
per live Durable Object instance, so eviction or restart resets it.

## The configuration file

`exportconfig` is a document, and a document can live in a repository. The format is `bind.ws/relay-config/2`: `policy`, `members`, `bans`, `addresses`, `banned_events`, `kinds` and `retention`, each a section, and a section the file leaves out is left alone when it is applied, so a file may carry the rules and nothing about people. The schema is at `https://bind.ws/relay-config.schema.json`; put it in `$schema` and the editor checks the file as you type. JSONC is fine: comments and trailing commas.
Expand Down
18 changes: 17 additions & 1 deletion docs/14-http-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Any request with `Accept: application/nostr+json` answers the NIP-11 document, w
|---|---|---|---|---|
| `/` | GET | none | the console, one page for visitors and owner alike | 200 |
| `/` | GET with `Accept: application/nostr+json` | none | NIP-11: rules, limits, retention, `self`, `lease` while leased, `succession_pending` while warning | 200 |
| `/` | POST, `content-type: application/nostr+json+rpc` | NIP-98 | NIP-86 management, `{ result }` or `{ error }` | 200; 400 invalid; 401 bad signature; 403 not allowed; 409 conflict |
| `/` | POST, `content-type: application/nostr+json+rpc` | NIP-98 | NIP-86 management, `{ result }` or `{ error }` | 200; 400 invalid; 401 bad signature; 403 not allowed; 409 conflict; 429 active relay operation |
| `/people` | GET | none | `{ public, self, host, people }`, the members when the directory is public | 200 |
| `/terms` | GET | none | the join terms as a page | 200; 404 none set |
| `/signer.js` | GET | none | the NIP-46 client bundle, cached a week | 200 |
Expand Down Expand Up @@ -97,6 +97,22 @@ unmatched refs are hidden and scheduled for deletion, but immutable Git
objects remain in retained storage. The 128-transaction ceiling can prevent
physical cleanup; it does not make those bytes free.

The owner can inspect one accepted repository through the NIP-86
`gitstorage` method at the relay root. It performs a bounded, read-only walk
of the physical R2 prefix and compares it with the live Git dependency set.
The result reports physical, live, unreferenced and unknown objects by class,
SQL reservations and `reservationMinusListedBytes`, together with operation
counts for diagnostics, limits and capture time. These counts are not tenant
billing meters. Unreferenced does not authorize deletion:
there is no collector or automatic storage reclamation. A complete report is
required, so a changed root or any inventory budget exhaustion returns an
error instead of partial data. The method has a 60-second per-instance
cooldown; a Durable Object restart or eviction resets that cooldown.

| Method | Parameters | Auth | Answers | Status |
|---|---|---|---|---|
| `gitstorage` | repository owner hex pubkey, identifier | NIP-98, owner with the storage action | bounded physical and live inventory, reservations and limits | 200; 400 invalid parameters; 403 inactive, fuel or role; 404 feature or repository unavailable; 413 inventory limit; 429 cooldown or another repository operation; 503 storage unavailable |

## Custom domains

These NIP-86 methods are owner-only and use the relay's normal NIP-98 RPC
Expand Down
Loading