Onomancy

Warning

Alpha software. Interfaces, wire formats, and specifications change without notice — use at your own risk.

A local-first edgename protocol: human-meaningful names over self-certifying keys, with optional DNSSEC-rooted global names layered on top.

This repository contains:

• protocol specifications
• design rationale
• onomancer (the reference implementation)

Name	Anchor	Authority	Shareable
automerge:3RFyJz…/foo	doc anchor	an Automerge URL; the doc ID is an ed25519 verifying key, self-certifying	yes
~/bob/pics	local petname	your signed root doc	no
@expede.wtf/foo	DNSSEC-rooted	chain from the IANA root KSK	yes

All three name forms resolve to an Automerge document whose ID is an ed25519 verifying key (via Keyhive) — a self-certifying identity, and the root that resolution starts from. Petnames and DNS names are naming layers over those documents, so an account created offline already has a globally shareable name, and binding a domain later adds a memorable spelling for the same identity. No migration, ever.

DNS-rooted names verify locally, from a baked-in IANA root KSK through a DNSSEC-protected TXT record to a signed certificate carried inside the document it binds (or received by gossip). The zone says which document; the certificate says which hostnames that document accepts. Neither direction alone is a binding — anyone controlling any signed zone can name any document — so a resolved name is not an authenticated one until both agree. Verified bindings are self-authenticating records: they can be gossiped peer-to-peer (Bluetooth at a field campout, QR codes) and re-verified by the receiver with no trust in the sender.

Design

See specs/ for the normative protocol specifications (path resolution, DNS anchoring, petname anchoring, serialization), and design/ for informal deep dives into why the design is how it is.

Workspace

Crate	Purpose
onomancy_core	Substrate-neutral kernel: generic name grammar (Name<A>), digests, signed-unit skeleton, wire primitives
onomancy_dnssec	The DNS anchoring protocol: @ names, certificate/statement/TXT codecs, sans-IO RFC 4034/4035 validation, IANA trust anchors baked in
onomancy_protocol	Sans-IO machines: resolution walk, comparison ladder, binding-cache derivation
onomancy_automerge	Automerge substrate adapter: namestores, decision documents, petnames
onomancy_chain	Sans-IO DNSSEC chain building: questions out, records in, framed links
onomancy_publish	Ceremonies (bind · refresh · rotate · migrate) emitting self-verified Plans
onomancy_keyhive	Keyhive authority verification: delegation-chain replay behind AuthorityVerifier
onomancy_hickory	Host chain courier: stub DNS transport driving the chain builder
onomancy_wasm	Wasm/JavaScript bindings, DoH chain courier, live browser demo
onomancer	The agent (binary): resolve · name · keygen · vouch · bind · refresh · rotate · migrate · record · watch

Libraries implement the protocol (onomancy_*); agents that practice it are onomancers (onomancer_*).

graph TD
    subgraph pure ["sans-IO: pure functions (host + Wasm)"]
        core["onomancy_core<br/><i>substrate-neutral kernel:<br/>Name&lt;A&gt; · digests · Signed · wire</i>"]
        dnssec["onomancy_dnssec<br/><i>the DNS anchoring protocol:<br/>@ names · units · TXT · validation</i>"]
        proto["onomancy_protocol<br/><i>machines: resolve · ladder · derive</i>"]
        chain["onomancy_chain<br/><i>chain-building state machine<br/>(questions out, records in)</i>"]
        publish["onomancy_publish<br/><i>ceremonies → Plans</i>"]

        subgraph adapters ["substrate adapters (pure over held documents)"]
            automerge["onomancy_automerge<br/><i>namestores · decision view ·<br/>Head ⇄ ChangeHash</i>"]
            keyhive["onomancy_keyhive<br/><i>delegation-chain verification</i>"]
        end
    end

    subgraph network ["network IO (untrusted byte couriers)"]
        hickory["onomancy_hickory<br/><i>host chain fetching</i>"]
        wasm["onomancy_wasm<br/><i>browser bindings · DoH fetch</i>"]
    end

    onomancer["onomancer (binary)<br/><i>resolve · name · keygen · vouch · bind<br/>refresh · rotate · migrate · record · watch</i>"]

    dnssec --> core
    proto --> dnssec
    proto --> core
    chain --> dnssec
    chain --> core
    hickory -- "drives" --> chain
    wasm -- "drives" --> chain
    publish --> proto
    automerge -- "implements Namestore" --> proto
    keyhive -- "implements AuthorityVerifier" --> proto
    hickory -- "implements ChainProvider" --> dnssec
    wasm -- "implements ChainProvider" --> dnssec
    onomancer --> publish
    onomancer --> hickory
    onomancer --> automerge
    onomancer --> keyhive

Loading

The crate layout follows the role stack (verifier / publisher over one pure core), not client/server: every participant is a verifier and servers are keyless byte couriers. Everything outside the network boundary is pure: cryptographic verification (DNSSEC chains, Keyhive delegation proofs) runs over supplied bytes against locally-held trust anchors, and document reads (namestores, decision state) run over locally-held replicas — statements carry their authority proofs verbatim and resolution never blocks on sync, so gossip is enough. The substrate adapters differ from the algorithm crates only in what they depend on (Automerge/Keyhive library types), not in purity; replication and persistence belong to the substrate and the agent, never to these crates.

Development

With Nix (flakes enabled):

nix develop   # rust 1.91, wasm toolchain, cargo-* utilities, command menu
menu          # list dev-shell commands (rust:*, wasm:*)

Or bring your own toolchain pinned by rust-toolchain.toml:

cargo test --workspace --all-features
cargo clippy --workspace --all-features --all-targets

See HACKING.md for the engineering patterns and abstractions, and GUIDANCE.md for publisher and verifier operational notes.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.