110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# Argand Site Registry
|
|
|
|
Evidence-backed website identity and regional resolution, as a Rust library and CLI.
|
|
|
|
Look up an entity's names, aliases and websites; inspect each source assertion;
|
|
resolve an explicitly reviewed primary or regional destination. Sources, conflicting
|
|
claims, licenses and review history remain available for audit. Everything runs
|
|
locally with SQLite. No search engine, hosted account or GPU is required.
|
|
|
|
`facebook → Facebook → facebook.com` is a name-to-entity-to-registrable-domain
|
|
lookup. The retained real Wikidata Facebook record has `www.facebook.com` and
|
|
`m.facebook.com` as distinct properties. Its Amazon record includes `amazon.com`,
|
|
`amazon.co.uk` and `amazon.de` on the same entity. Similar hostname spelling never
|
|
establishes common ownership. Imported links await review before `resolve` can
|
|
return a destination; source confidence is not a malware-safety guarantee.
|
|
|
|
## Build and try it
|
|
|
|
Linux is the currently validated platform. Install Rust (tested with 1.98.1; the
|
|
inherited minimum is 1.97), a C compiler, CMake, Perl and OpenSSH (`ssh-keygen`).
|
|
Python 3.11+ is needed for release tooling and the Python example. SQLite is built
|
|
with the binary. From the root of this source checkout or extracted release:
|
|
|
|
```bash
|
|
cargo fetch --locked
|
|
cargo build --release --locked --offline -p argand-site-registry
|
|
./target/release/argand-site-registry --help
|
|
```
|
|
|
|
If your Cargo configuration sets a different target directory, set
|
|
`CARGO_TARGET_DIR="$PWD/target"` before these commands. To install the CLI:
|
|
|
|
```bash
|
|
cargo install --path crates/argand-site-registry --locked --offline
|
|
argand-site-registry --help
|
|
```
|
|
|
|
Run the native all-source example in a **new directory outside the checkout**:
|
|
|
|
```bash
|
|
ARGAND_REGISTRY_E2E_OUTPUT=/tmp/site-registry-example \
|
|
cargo test -p argand-site-registry --test cli --locked --offline -- --nocapture
|
|
```
|
|
|
|
It imports synthetic Wikidata, Majestic, CrUX, Curlie and PSL fixtures, checks
|
|
idempotency, joins explicitly reviewed identities, approves a destination, signs
|
|
and activates it, revokes it, and rejects rollback past that revocation. Fixture
|
|
signing keys and approvals are disposable test material. All production inputs
|
|
belong in a configurable data/cache directory outside the source checkout.
|
|
|
|
Follow the [operator guide](crates/argand-site-registry/README.md) for actual
|
|
downloads, imports, regional reviews, signed datasets and weekly candidate updates.
|
|
CrUX acquisition requires explicit credentials and a billing cap. No source
|
|
downloads or scheduled jobs run during installation or tests.
|
|
|
|
## Use it in another project
|
|
|
|
The [Rust example](crates/argand-site-registry/examples/lookup.rs) opens a generation
|
|
once with an externally trusted receipt hash and returns the full lookup envelope.
|
|
The [Python example](examples/lookup.py) calls the same native CLI; it does not
|
|
implement a second resolver. Both preserve attribution and fact provenance.
|
|
|
|
```bash
|
|
cargo run --locked --offline -p argand-site-registry --example lookup -- \
|
|
--generation /data/registry/generation --pin "$REGISTRY_TRUSTED_PIN" --query facebook
|
|
|
|
python3 examples/lookup.py --binary ./target/release/argand-site-registry \
|
|
--generation /data/registry/generation --pin "$REGISTRY_TRUSTED_PIN" --query facebook
|
|
```
|
|
|
|
Obtain the pin from a trusted publisher channel or verify the release signature
|
|
against an independently configured key. Reading a hash from the same untrusted
|
|
download does not authenticate it. Never turn `lookup.candidates[0]` into an
|
|
automatic destination: use the native `resolve` result and your application's
|
|
own admission policy. A null destination is a meaningful abstention.
|
|
|
|
The [consumer contract](docs/CONSUMERS.md) covers Rust dependencies, CLI JSON,
|
|
SQLite/JSONL distribution, compatibility and Argand's eventual upstream cutover.
|
|
|
|
## Sources and trust
|
|
|
|
Wikidata (CC0), Majestic Million (CC BY 3.0), CrUX (CC BY 4.0), Curlie (CC BY 3.0)
|
|
and the Public Suffix List (MPL 2.0) remain logically separate. Read the exact
|
|
[source licenses and attribution rules](LICENSE_SOURCES.md) before redistribution.
|
|
Curlie attribution applies to names and categories as well as descriptions.
|
|
|
|
The [trust policy](docs/TRUST.md) explains enforced checks, publisher responsibilities,
|
|
evidence standards, expiry and revocation. [CONTRIBUTING.md](CONTRIBUTING.md),
|
|
[GOVERNANCE.md](GOVERNANCE.md) and [SECURITY.md](SECURITY.md) cover contributions,
|
|
decisions, disputes and incidents. Pull requests cannot directly approve destinations.
|
|
|
|
## Development and releases
|
|
|
|
```bash
|
|
cargo fetch --locked
|
|
bash scripts/check.sh
|
|
```
|
|
|
|
The check runs formatting, all-target compilation, strict Clippy, Rust tests and
|
|
documentation, Python release tests, and native Rust/Python consumer parity.
|
|
[RELEASING.md](docs/RELEASING.md) covers deterministic source archives, signature
|
|
verification and rebuilding outside the checkout. The Forgejo workflow requires
|
|
a dedicated isolated runner; it has no signing or dataset-promotion authority.
|
|
|
|
The code remains **AGPL-3.0-or-later**; the complete license is in [LICENSE](LICENSE).
|
|
Original attribution is retained. [UPSTREAM.json](UPSTREAM.json) records the signed
|
|
Argand extraction revision and original file hashes. This initial independent
|
|
package preserves the existing registry runtime and schema. Hosted publication,
|
|
runner provisioning and changing Argand's dependency require separate completion;
|
|
the initial extraction does not itself establish any of those states.
|