74 lines
4.7 KiB
JSON
74 lines
4.7 KiB
JSON
{
|
||
"name": "hdms",
|
||
"section": 1,
|
||
"title": "Hyperdrive management (HDMS)",
|
||
"synopsis": [
|
||
"hdms help",
|
||
"hdms list",
|
||
"hdms create LABEL",
|
||
"hdms add LABEL KEY",
|
||
"hdms remove LABEL",
|
||
"hdms show LABEL",
|
||
"hdms invite [--read-only] [--rw] [LABEL]",
|
||
"hdms pair [--persist | --no-persist] INVITE"
|
||
],
|
||
"description": "When the booter wires ctx.runHdms, hdms manages extra Hyperdrives registered on the personal drive at /.bare/hdms/registry.json. Writable drives use a local Corestore namespace and replicate via Hyperswarm; read-only drives open by z32 public key. Writable replicas (after pair with an RW invite) store the Hyperdrive key (z32), the metadata signer public key (z32 field signerKey), and the writer secret (128 hex chars) in the registry—Hyperdrive’s public key is usually a manifest id, not the same bytes as the signer public key. Subcommands invite and pair use Autopass for blind pairing. Read-only drive offers use Autopass key bare-os-hdms/pending-share with {label,key}. Read/write offers use bare-os-hdms/pending-share-rw with {label,key,signerKey,writerSecretHex} so older peers that only poll pending-share do not silently mount an RW invite as read-only. hdms pair takes the invite string plus optional flags; the local mount name is the inviter label, or label-2, label-3, ... if that name is already used. By default the new mount is written to registry.json (survives reboot). hdms pair --no-persist opens the mount for this session only (ephemeral; hdms remove still works). hdms pair --persist is an explicit no-op alias for the default. hdms pair times out if the inviter never answers (BARE_OS_HDMS_PAIR_WAIT_MS, default 120000 ms). After pair, BARE_OS_HDMS_PAIR_SHARE_WAIT_MS (default 25000) bounds polling for pending share records. Flag --read-only on invite sets the peer Autopass writer role, not Hyperdrive writability. Flag --rw on invite with LABEL publishes the metadata writer secret onto the Autopass ledger: anyone who can read that replicated Autobase can write to the drive—treat RW invites as highly sensitive.",
|
||
"options": [
|
||
{
|
||
"flag": "--read-only",
|
||
"meaning": "With invite: Autopass stores the peer as a read-only writer. Often breaks hdms pair because AutopassPairer awaits deleteInvite (append) on the peer. Prefer omitting this flag; HDMS mounts stay read-only without --rw regardless."
|
||
},
|
||
{
|
||
"flag": "--rw",
|
||
"meaning": "With invite LABEL: offer read/write replica; Autopass bare-os-hdms/pending-share-rw carries {label,key,signerKey,writerSecretHex}. Requires LABEL. Extremely sensitive."
|
||
},
|
||
{
|
||
"flag": "--no-persist",
|
||
"meaning": "With pair: do not write the new mount to /.bare/hdms/registry.json (ephemeral until hdms remove or session ends)."
|
||
},
|
||
{
|
||
"flag": "--persist",
|
||
"meaning": "With pair: explicit default—mount is saved to registry (same as omitting --no-persist)."
|
||
}
|
||
],
|
||
"keywords": [
|
||
"hdms",
|
||
"hyperdrive",
|
||
"hyperswarm",
|
||
"mount",
|
||
"autopass",
|
||
"pair",
|
||
"invite"
|
||
],
|
||
"bareOsNotes": "Requires unlocked identity and active HDMS; see handbook ch.5.",
|
||
"environment": [
|
||
"BARE_OS_HDMS_PAIR_WAIT_MS — max milliseconds to wait for blind pairing to complete before hdms pair fails (default 120000, max 600000)",
|
||
"BARE_OS_HDMS_INVITE_CLEAR_MS — max milliseconds to wait for the prior @autopass/invite row to leave the HyperDB view after deleteInvite before minting a new invite (default 30000, max 120000)",
|
||
"BARE_OS_HDMS_PAIR_READY_MS — after pair connects, max milliseconds to wait for Autobase membership/view before polling share keys (default 45000, max 120000; set 0 to skip)",
|
||
"BARE_OS_HDMS_PAIR_SHARE_WAIT_MS — milliseconds to poll Autopass for bare-os-hdms/pending-share and bare-os-hdms/pending-share-rw after hdms pair (default 25000)",
|
||
"HYPERSWARM_BOOTSTRAP — comma-separated bootstrap list for swarm (invite/pair and replication)"
|
||
],
|
||
"examples": [
|
||
{
|
||
"caption": "create writable drive and list mounts",
|
||
"code": "hdms create myvol\nhdms list"
|
||
},
|
||
{
|
||
"caption": "read-only mount by public key",
|
||
"code": "hdms add mirror 8j3nbznnxcp7p668jkik75d83s8j7ew9chq4r34cxe8qfrifzmfo"
|
||
},
|
||
{
|
||
"caption": "invite including drive myvol; peer mounts read-only",
|
||
"code": "hdms invite myvol\n# peer:\nhdms pair yryu9hwicdkddw5x81hnw7453mu7mtgaq6s3qguar6ar6h1dgk9pdz3nuea7madc47hcsnikzqegdmzwnb86k67yo1bwnhdd7mtncz9xmo"
|
||
},
|
||
{
|
||
"caption": "read/write invite (writer secret on Autopass); peer pairs",
|
||
"code": "hdms invite myvol --rw\n# peer:\nhdms pair <INVITE>"
|
||
},
|
||
{
|
||
"caption": "pair without saving to registry (session-only mount)",
|
||
"code": "hdms pair --no-persist <INVITE>"
|
||
}
|
||
]
|
||
}
|