threadline-core

Threadline's agent-to-agent fundamentals, with no framework attached. ESM only (import, not require), Node 20 or later. It's used by threadline-mcp (any agent, through MCP) and by Instar, so both speak exactly the same protocol and can pair with each other.

What's in it:

• Identity: Ed25519 keys; an agent's fingerprint is the first 16 bytes of its key.
• Encrypted, signed envelopes: X25519 (derived from the identity key) with HKDF and XChaCha20-Poly1305, and an Ed25519 signature over the canonical envelope. Byte-compatible with Instar, which the tests prove against vectors generated by Instar's own code. What this gives: confidentiality and sender authentication. What it does not give: forward secrecy against the recipient's key. Each message uses a fresh ephemeral key, but it is combined with the recipient's long-term key, so whoever later obtains that key can decrypt every past message recorded for it. The envelope also does not stop replay by itself; callers keep a message-id ledger (threadline-mcp does, plus a freshness window for credentials).
• Pairing by invite: one person sends an invite privately, the other person approves it, and the first person finishes. The accept carries a MAC under a one-time secret and a signature, and both sides check keys against the relay's public card. If an invite is used twice, the first acceptor is paused and one alarm is raised.
• Pinned keys: PinnedKeyStore, a 0600 file that never swaps a verified key.
• Pinning: the full 32-byte identity key is stored and compared, and small-order or non-canonical keys are refused (isAcceptableIdentityKey). A pin also carries encryptedSeenAt, the first time that peer sent encrypted chat, after which plaintext in its name is refused.
• The credential gate: credentialSendKey allows a secret only to a mutual-verified peer whose pairing still matches your current key, and returns the only key it may be encrypted to (derived from the pinned identity, never one the relay supplied). credentialAcceptFrom gates what you receive, with the same key-binding check when you pass your own key.
• Safe stores: a store file that is not valid JSON is moved aside and reported, never overwritten; one that cannot be read stops the store from starting.

What it leaves to you: EnvelopeCrypto.decrypt checks the signature, the key binding and the ciphertext. Checking that the envelope is addressed to you (to), how old it is, and whether you have seen it before (replay) is the caller's job; threadline-mcp does the replay check by sender and message id.

The person, never the agent, approves pairing. How they're asked is up to the host: Instar uses its dashboard and Telegram buttons, and threadline-mcp uses MCP elicitation.

Spec: docs/specs/threadline-standalone-pairing.md in the Instar repository.