Module linkmd 

The link.md client — the five interconnect verbs dbmd speaks against a hub: resolve, sync, grant, propose, subscribe.

One binary, two specs (the git precedent: one binary carries both the object format and the wire protocol). The db.md FORMAT is untouched by this module: a store never needs link.md to be valid db.md, record files stay plain markdown, and SPEC.md reserves only the @brain/id address shape. Everything with a wire or a trust boundary — addressing across stores, pulling/pushing a hosted copy, capability grants, the propose door, feed polling and signed-entry verification — lives here, as a client capability, never a format requirement.

What this client speaks

The v0 HTTP binding a hub serves under its base URL:

verb	binding
resolve	GET /api/hub/brains/<brain> (the brain card); records are read from the exact signed snapshot pack named by that card’s verified feed head
sync (pull)	GET /api/hub/brains/<brain>/export?format=pack&atSeq=<n>&feedHash=<hash> — the exact verified snapshot
sync (push)	POST /api/hub/brains/<brain>/push for small snapshots; presign/upload/commit for large snapshots
grant	GET / POST /api/hub/brains/<brain>/grants, DELETE /api/hub/brains/<brain>/grants/<id>
propose	POST /api/hub/sites/<handle>/inbox — evidence in, without trust (unauthenticated by design)
subscribe	GET /api/hub/brains/<brain> + /feed for a locally verified signed head

Configuration — no default hub, credential never in the store

There is no built-in hub endpoint: the toolkit is neutral and a hub is whatever the user points it at. Resolution order for the hub URL:

1. the --hub <URL> flag,
2. the DBMD_HUB_URL environment variable,
3. the hub = <URL> line in the store-local .dbmd/config file (toolkit state, not store content — the walkers already skip hidden directories, so .dbmd/ never syncs, indexes, or validates).

The credential is the DBMD_HUB_KEY environment variable, full stop. It is deliberately not read from .dbmd/config: a secret inside the store tree is one commit or one push away from leaking. A store-selected hub may receive an ambient bearer or agent key only when DBMD_HUB_CREDENTIAL_ORIGIN binds it to that exact origin. Identity pins and monotonic feed checkpoints live in the user’s global state directory, never in store-controlled .dbmd/.

Non-HTTPS hubs are refused (the bearer key must never travel in cleartext) with a loopback exemption for local development.

v0 honesty

This client binds to what a hub enforces today: grantees are hub principals (an email), grant scopes are store-path prefixes, pushes are whole-store snapshots, and subscribe reports feed-head movement. The hub signs each committed snapshot in a hash-chained feed with a per-brain Ed25519 identity. This client verifies the rotation chain, signer epochs, monotonic feed checkpoint, snapshot token, and content-addressed pack before untrusted bytes touch their destination.

Structs

Address

A parsed @brain[/target] address. brain is a hub brain reference — the brain’s ULID id (works for any caller, including cross-party on a public brain) or a slug (which a hub resolves only against the caller’s own brains; slugs are unique per owner, not globally).

AgentSigningKey

A loaded agent signing key: the PKCS#8 secret plus its derived public multikey. Debug never prints key material.

GeneratedAgentKey

What dbmd key generate returns: the public identity to register plus where the secret landed.

Head

One observation of a brain’s feed head.

HubConfig

The resolved client configuration for one invocation.

HubResponse

One hub response: the status plus the parsed JSON body when there was one.

MirrorReport

What dbmd mirror materialized.

PullReport

What a pull materialized.

RotationReport

What dbmd key rotate returns.

V2BulkConfirmation

Exact approval token returned by a permissioned v2 bulk preview.

VerifiedMirrorMaterial

Fully re-verified mirror material suitable for a read-only re-server.

Enums

AddressTarget

What the part after @brain/ names.

Capability

The two capabilities a v0 hub enforces.

LinkError

Everything that can go wrong on the wire or at its edges. Each variant maps onto one stable CLI error code; messages are single-line and never echo the credential.

V2ConflictChoice

One explicit resolution for a previously preserved private conflict bundle.

Constants

AGENT_KEY_FILE_ENV

Environment variable naming the PATH of an agent signing key file (link.md §8 LinkMD-Sig proof of possession). When set, authenticated requests are signed per-request with the agent’s Ed25519 key instead of carrying a bearer: the signature binds method + path + body + a ±60s window, so nothing reusable ever crosses the wire or lands in a log or an agent transcript. The file holds the base64url PKCS#8 key minted by dbmd key generate; the path is not a secret, the file is (mode 0600).

ALLOW_PRIVATE_OBJECT_URL_ENV

Explicit development escape hatch for object-store URLs on loopback/private networks. Production hubs must return public HTTPS URLs. A local loopback hub is allowed to use local object URLs without this switch.

ALLOW_PRIVATE_REGISTRY_HOME_ENV

Explicit test/development escape hatch for registry homes on loopback or private networks. Production federation rejects every non-public resolved address and pins the validated DNS answer into the HTTP agent.

BRAIN_KEY_FILE_ENV

Environment variable naming the PATH of a self-custodied BRAIN key file (link.md §2.4). When set, sync --push signs each feed entry locally and ships it through the pack flow — the hub verifies and stores the exact client bytes and can never sign for the brain. Same file format as agent keys (dbmd key generate).

CONFIG_REL_PATH

The store-local config file, relative to the store root. Holds non-secret toolkit state (hub = <URL>); hidden, so every store walk skips it.

HUB_CREDENTIAL_ORIGIN_ENV

Explicit origin binding required before an ambient bearer or agent key may be sent to a hub selected by untrusted store-local configuration. The value is an origin (https://host[:port]), not an arbitrary URL path.

HUB_KEY_ENV

Environment variable carrying the hub bearer credential. The bearer credential source — see the module docs for why it is never store-based.

HUB_URL_ENV

Environment variable naming the hub base URL (e.g. https://hub.example.com).

MAX_PROPOSE_BYTES

The hub’s inbox cap on one propose submission body, mirrored client-side so an oversized body fails before the upload, not after (the same fail-before-upload contract as the push caps). Public so the CLI can pre-check a --body-file from file metadata without reading it.

MIRROR_REL_DIR

The mirror state directory, relative to the mirror root.

STATE_DIR_ENV

Override for dbmd’s user-owned trust/checkpoint root. Must be absolute. Intended for managed installations and hermetic tests; untrusted stores cannot select it.

Functions

collect_push_files

Collect the files a push sends: the store’s owned source text — DB.md, assets.jsonl when present, the canonical curator timeline (log.md plus rotated log/*.md archives), and every content .md under records/ and sources/. Derived index.* catalogs remain local because the receiver rebuilds them. Returns (store-relative path, content) pairs, path-sorted.

content_sha256

SHA-256 hex for content a signed manifest names. Exposed for the thin dbmd serve adapter; cryptographic verification remains centralized here.

content_sha256_reader

SHA-256 a stream with a fixed-size working buffer.

feed_entry_hash

SHA-256 hex of one feed entry’s stored bytes (exact JSON + "\n") — the entry hash every consumer recomputes (SPEC §5.3).

generate_agent_key

Mint a fresh Ed25519 agent keypair. The secret is written to out (base64url PKCS#8, one line, 0600, refusing to overwrite); only public identity is returned. The private key never enters a store and never travels — requests carry per-request signatures instead (link.md §8).

grant_issue

Issue (or refresh) a grant on brain to grantee — a hub principal named by email in v0 (the protocol’s near-term simplification; key-named grantees arrive with the signing layer). scope is a store-path prefix (the hub’s enforcement unit); until an ISO 8601 expiry, absent = until revoked.

grant_list

List the active grants (and pending invites) on brain. Owner-side.

grant_revoke

Revoke a grant (or cancel a pending invite) by id. Owner-side; revocation is soft on the hub (the audit trail survives).

has_v2_sync_baseline

Whether this exact hub/brain/path coordinate has an accepted v2 sync baseline. CLI dispatch uses this to keep checkout identity sticky even when a damaged DB.md makes strict store-open fail.

has_verified_local_scoped_view

True only when this store carries the exact generated marker for a local link.md scoped view. This is presentation context, never authorization; the hub remains the only authority for reads and writes.

head

Read and locally verify the brain’s current signed feed head. Identity rotation is accepted only through an old-key-signed chain rooted at the local TOFU anchor; sequence and hash checkpoints reject rollback and equivocation across invocations.

hub_config

Resolve the client configuration: flag_hub beats HUB_URL_ENV beats the hub = line in <dir>/.dbmd/config; no fallback default exists. The credential comes from HUB_KEY_ENV alone and is validated as a clean header token (never echoed on failure).

is_valid_handle

A published-site handle (the propose target). Same lexical shape as a slug.

load_signing_key

Load and validate a signing-key file (agent or brain — same format): one base64url line of PKCS#8. Public so dbmd key rotate can load the old key explicitly.

mirror

Replicate a brain with full verification (link.md §5.4 over the WHOLE chain, not just the head): every entry’s signature, hash, sequence contiguity, prev-hash linkage, rotation chain, and exact signed pack are checked in a sibling staging directory. Only then is the old mirror swapped out through an atomic directory exchange. Every stage, install, and cleanup operation is relative to one held no-follow parent-directory capability, so renaming an ancestor cannot redirect any write or deletion.

proposal_accept_exact

proposal_list

proposal_reject

proposal_show

propose

Submit body to the published site handle, addressed to its app page app (a page that declares the write-inbox capability). Deliberately unauthenticated — this is the cross-party door; the submission lands as evidence in the owner’s sources/inbox/, never as truth, and the owner’s curator accepts or rejects it. Returns the hub’s {id, path} receipt.

rebind_v2_alias

Explicitly replace one mutable alias binding after the operator reviews the exact deleted/re-created brain ids. Canonical checkpoints are never removed or rewritten, so old history remains pinned and the new brain establishes its own independently verified trust chain.

relocate_v2_sync_baseline

Rebind one verified incremental baseline after its checkout directory was moved without changing the checkout bytes. Baselines deliberately live in private trust state and are path-bound, so callers performing an atomic staged publish must cross this explicit boundary instead of silently turning the moved checkout into a baseline-less clone.

resolve

resolve_registry

Resolve a bare @handle through the federation registry (link.md §7.1, E5): look the handle up in the hub’s registry, fetch the brain card from the returned HOME node, and PIN — the card’s identity fingerprint must equal the registry’s, or resolution fails. Returns the card enriched with the resolved home, or Ok(None) when the registry has no such handle (so the caller can fall back to a direct lookup).

rotate_brain_key

Rotate a self-custodied brain’s key: mint a fresh keypair, build the §9.1 statement — the new key plus exact prior feed boundary, signed by the OLD key in normative serialization — and send it to the hub. The new secret is durably created at 0600 before the POST; an existing output is reused for idempotent retry/reconciliation. The old key is left untouched.

safe_store_rel_path

True when p is a store-relative path this client will read from or write to disk: relative, no .., no empty or dot-leading segment (which shields .dbmd/ and .git/), and only the hub-portable character set. Applied to every path an export hands us (the hub is not trusted with local layout) and to every path a push sends (mirroring the hub’s own gate).

sync_conflicts

Inspect or prune private conflict-control state. Ordinary pruning removes only expired completed bundles and interrupted bundles with no plan.json; corrupt completed plans fail closed. all is an explicit local discard of every well-addressed bundle and never changes hosted brain data.

sync_converge

Converge one established permissioned-v2 checkout in both directions.

sync_converge_with_controls

Bidirectional convergence with optional exact withdrawal intents.

sync_converge_with_options

Bidirectional convergence with optional exact bulk-preview confirmation.

sync_pull

Pull the granted slice of brain to out (default: ./<slug>). Every exported path is safety-gated before it touches disk; files are written atomically; nothing local is ever deleted (locals the export lacks are reported in extra_local instead). Returns the report; rebuilding the local index catalog afterwards is the caller’s (cheap, optional) step.

sync_push

Push files to brain as a whole-store snapshot — the hub’s push semantics: the hosted copy becomes exactly this set (pull first if the hosted side may have records the local copy lacks). Client-side caps mirror the hub’s JSON-path limits so an oversized push fails before the upload.

sync_push_incremental

Negotiate v2 and send only local changes. A v1 hub retains the existing whole-snapshot behavior until its brain advertises the new profile.

sync_push_incremental_with_controls

Incremental push with explicit permissioned current-host withdrawal.

sync_push_incremental_with_options

Incremental push with both local-policy adoption and an optional exact permissioned bulk-preview confirmation.

sync_push_incremental_with_policy

The explicit .sevralocal adoption form. Ordinary sync never uploads a path that became eligible because local policy was weakened or removed.

sync_resolve_conflict

Resolve one exact private conflict plan. Drift never lowers a precondition: the remote head/view and every original local coordinate are rechecked before either an explicit local install or a fresh normal commit.

verify_mirror_material

Re-verify mirror metadata, every signature/hash/rotation boundary, and the exact snapshot pack before dbmd serve exposes any bytes.

verify_mirror_material_with_pack_hash

Re-verify mirror metadata against a snapshot digest computed from a held no-follow file capability. This lets dbmd serve authenticate and retain a large pack without ever buffering the pack in process memory.

Type Aliases

LinkResult

Result alias for link.md client operations.