Identity spoofing: Every account is a cryptographic key pair. Nobody can impersonate you without your private key.

Content tampering: Every document change is cryptographically signed. Modifications are detectable and attributable.

Server-side censorship: Your content exists as signed blobs that any peer can host. No single server can permanently remove your data.

Unauthorized edits: Access control is enforced through cryptographic capabilities, not server permissions. Only accounts with valid delegation chains can write.

Platform lock-in: Your identity and content are portable. You can move between gateways, self-host, or use multiple peers simultaneously.

No encryption at rest: Documents are signed but not encrypted. Anyone who can access a blob can read it. Private documents are not yet supported at the protocol level.

No key recovery: If you lose your private key, your identity is gone. There is currently no social recovery or multi-device key management built in.

Network-level metadata: While content is authenticated, network traffic patterns (who syncs what, when) are visible to peers and gateways.

Availability depends on peers: If no peer hosts your content and you go offline, your documents become temporarily unavailable.

Every account in SHM is an Ed25519 key pair. Ed25519 was chosen for its speed, small key/signature sizes (32 bytes / 64 bytes), and resistance to timing attacks. It's the same algorithm used by SSH, Signal, and many blockchain systems.

Account identifiers are the public key encoded as a did:key URI using the Multicodec ed25519-pub prefix (0xed). For example: z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6

Keys are derived from a BIP-39 mnemonic seed phrase using the derivation path m/44'/104109'/0', where 104109 is the ASCII encoding of 'hm' (for HyperMedia). This follows the same hierarchical deterministic key derivation used in cryptocurrency wallets, ensuring keys can be regenerated from the seed phrase.

The seed phrase is your master secret. Anyone with it can derive your private key and sign documents as you. Store it securely — ideally offline, never in plain text on a connected device.

Document changes are encoded as CBOR (Concise Binary Object Representation) blobs. CBOR provides deterministic encoding, which is critical for signatures — the same logical content always produces the same bytes, so signatures remain valid across implementations.

Every blob is identified by its CID (Content Identifier) — a hash of its contents. This means blobs are self-verifying: if the hash matches, the content hasn't been tampered with. SHM uses CIDv1 with the dag-cbor codec and SHA-256 hash function.

Content addressing also enables efficient deduplication. If two documents include the same image, only one copy needs to be stored and transferred.

When you create or edit a document, the process works like this:

1. Your client constructs a change blob containing the operations (text edits, metadata changes, etc.) and references to parent blobs.

2. The signature field is filled with zeros (a placeholder of the correct length).

3. The blob is CBOR-encoded with the zero signature.

4. Your private key signs the entire CBOR-encoded bytes.

5. The zero signature is replaced with the real signature.

6. The blob is CBOR-encoded again with the real signature, producing the final blob.

This sign-then-embed approach means the signature covers everything in the blob except itself, and the final CID covers everything including the signature.

Any peer can verify a blob by: extracting the signature, replacing it with zeros, CBOR-encoding the result, and checking the signature against the author's public key. No server trust required — the math is the proof.

Document changes form a directed acyclic graph (DAG) through their parent references. Each change points to one or more previous changes, creating a causal ordering. This enables concurrent edits by different authors to be merged deterministically, while maintaining a complete history of who changed what and when.

WRITER: Can create and modify documents under the account. This is the primary collaboration capability.

Capabilities are created via the CreateCapability API, which produces a signed capability blob. The delegation chain is: account owner creates capability → grants it to another account → that account can now sign changes that peers will accept.

When a peer receives a document change from a non-owner account, it verifies the entire delegation chain: Does the owner's capability blob grant WRITER to this account? Is the capability blob properly signed by the owner? Is the change blob properly signed by the delegated account?

This chain is verified locally by every peer — no server needs to be consulted. Revocation works by publishing a new capability blob that excludes the revoked account, though propagation of revocations across the network is eventually consistent.

Currently, SHM documents are either public (anyone with the URL can read) or unlisted (not discoverable but readable if you have the URL). True private documents with encryption are not yet implemented at the protocol level. Access control currently governs write permissions, not read permissions.

Every peer has a libp2p peer ID derived from its key pair. Connections between peers are authenticated and encrypted using the Noise protocol framework. This means data in transit is protected even if the network path is compromised.

Gateways serve content over HTTP to make SHM documents accessible via web browsers. The trust model for gateways is important to understand:

Gateways can verify: All content they serve is cryptographically signed. They can verify signatures before serving, ensuring they don't distribute tampered content.

Gateways can NOT: Sign content on your behalf (they don't have your private key), modify content without detection (signatures would break), or permanently delete your content (other peers may have copies).

However, gateways CAN: Refuse to serve your content (censorship by omission), serve stale versions, or log who requests what content. Running your own gateway eliminates these risks.

Document synchronization uses a pull-based model where peers request specific resources. The sync protocol ensures that peers only accept properly signed blobs — a malicious peer cannot inject unsigned or mis-signed content into your local store.

Write your seed phrase on paper and store it in a secure physical location.

Never store your seed phrase in a cloud service, email, or chat message.

Consider splitting it across multiple locations for high-value accounts.

The seed phrase is the ONLY way to recover your account. Lose it and your identity is permanently lost.

Your private key is stored in the desktop app's local data directory. Encrypt your disk to protect it at rest.

If a device is compromised, assume your key is compromised. There is currently no key rotation mechanism — you would need to create a new account and re-publish your content.

For automated agents or servers, consider using a file-based keystore with restricted file permissions (chmod 600).

Use gateways you trust for content availability, but remember they cannot forge your signatures.

Self-hosting a gateway gives you full control over content serving and availability.

Push to multiple gateways for redundancy — if one goes down, your content is still accessible through others.

Only grant WRITER capabilities to accounts you trust. Once granted, they can publish changes under your account until revoked.

Review the delegation chain for any document you consume — check who has write access and whether the author history looks legitimate.

Use branching (CreateRef) for untrusted contributions — reviewers can fork, modify, and propose changes without needing write access to the original.

Centralized platforms trust the server completely. The server authenticates users, enforces permissions, and stores content. If the server is compromised, everything is compromised. If the company shuts down, your content may be lost. SHM eliminates the single point of failure but requires you to manage your own keys.

Git commits are signed (optionally), but most git workflows don't verify signatures. SHM makes signing mandatory — every change is signed, always. Git also doesn't have built-in access control; it relies on the hosting platform (GitHub, GitLab) for permissions. SHM bakes access control into the protocol itself.

AT Protocol uses DIDs and signed data repositories, similar in spirit to SHM. Key differences: AT Protocol relies on DID PLCs with a central registry for key rotation; SHM uses did:key with no registry (simpler, but no rotation). AT Protocol separates identity from hosting via PDSes; SHM separates identity from hosting via P2P sync. AT Protocol is optimized for social networking; SHM is optimized for document collaboration.

Nostr uses secp256k1 keys and relay-based distribution. Like SHM, identity is a key pair and content is signed. But Nostr events are standalone — there's no DAG structure or CRDT merging for collaborative editing. Nostr is better for ephemeral social content; SHM is better for persistent, collaboratively-edited documents.