packages/headless on the vault-adapter seam #51

New issue

Closed

opened 2026-09-21 18:04:31 +01:00 by cruelacid · 1 comment

cruelacid commented

2026-09-21 18:04:31 +01:00

Owner

Part of #37. Enables the Git mirror and the document API — build once, close three.

What Relay does

Not shipped. Headless sync is their issue #74; the maintainer says they are
"experimenting with, but haven't yet committed to on our roadmap". Their Git sync
works differently — see that issue.

Why ours must be shaped differently

Relay runs relay-git-sync as a server-side service that subscribes over
websocket, because their server can read plaintext. Ours cannot: the server
holds no keys and would hand out ciphertext under HMAC'd names.

So a headless Nectenda client must run where the keys are — the customer's
own machine or their own infrastructure. That is a different shape and arguably a
better one, and it should be explained rather than apologised for.

Why it is cheaper than it looks

packages/plugin/src/vault-adapter.ts is already a narrow, Obsidian-free
interface with an in-memory FakeVault behind it. A Node FsVault implementing
the same interface, plus the existing multiplexed provider, folder crypto and a
device identity, is a headless sync client.

The genuinely new decision

How an unattended process holds a passphrase. That is a
docs/security-model.md question before it is a code one, and it must be
answered there first. The current model — key cached in the OS credential store,
passphrase never leaving the device — does not obviously extend to a daemon.

Risk

risk:additive. A new package; the server is unchanged.

Verification

A headless client and a real Obsidian vault converge on the same folder, proven
in the e2e suite rather than by inspection.

Part of #37. **Enables the Git mirror and the document API — build once, close three.** ## What Relay does **Not shipped.** Headless sync is their issue #74; the maintainer says they are "experimenting with, but haven't yet committed to on our roadmap". Their Git sync works differently — see that issue. ## Why ours must be shaped differently Relay runs `relay-git-sync` as a server-side service that subscribes over websocket, because **their server can read plaintext**. Ours cannot: the server holds no keys and would hand out ciphertext under HMAC'd names. So a headless Nectenda client must run **where the keys are** — the customer's own machine or their own infrastructure. That is a different shape and arguably a better one, and it should be explained rather than apologised for. ## Why it is cheaper than it looks `packages/plugin/src/vault-adapter.ts` is **already** a narrow, Obsidian-free interface with an in-memory `FakeVault` behind it. A Node `FsVault` implementing the same interface, plus the existing multiplexed provider, folder crypto and a device identity, is a headless sync client. ## The genuinely new decision **How an unattended process holds a passphrase.** That is a `docs/security-model.md` question before it is a code one, and it must be answered there first. The current model — key cached in the OS credential store, passphrase never leaving the device — does not obviously extend to a daemon. ## Risk `risk:additive`. A new package; the server is unchanged. ## Verification A headless client and a real Obsidian vault converge on the same folder, proven in the e2e suite rather than by inspection.

cruelacid added this to the Phase 18 - Agents and headless milestone

2026-09-21 18:04:31 +01:00

cruelacid added the

labels

2026-09-21 18:04:31 +01:00

cruelacid referenced this issue

2026-09-21 18:08:51 +01:00