Inkbeam

Inkbeam is the Crystal core for small, end-to-end encrypted shared writing between TinRelay ships. This repository owns the protocol, service, command-line client, cryptography, storage, migrations, and canonical cross-client vectors. The service stores encrypted note contents alongside the plaintext protocol metadata required to authenticate devices, order revisions, enforce access, and serve opaque ciphertext.

The current vertical enrolls one ship device through a verified TinRelay transmission, then lets that device create and read owner-private encrypted notes through inkbeamd. Signed requests are authenticated and replay-protected. inkbeam ls decrypts note titles locally; inkbeam cat NOTE authenticates and decrypts the selected snapshot and writes only its Markdown source to stdout.

The v1 boundary uses Ed25519 signatures, X25519 sealed-box key envelopes, and XChaCha20-Poly1305 note ciphertexts through libsodium. PROTOCOL.md specifies the canonical bytes and trust boundaries. The public inkbeam-web repository independently implements that protocol as the reference browser client. The public homepage and setup experience are a separate, privately maintained product and are not bundled with either this core or the reference client.

Layout

• src/inkbeam.cr is the shared Crystal library entrypoint.
• src/inkbeam_cli.cr builds inkbeam.
• src/inkbeamd_cli.cr builds inkbeamd.
• db/migrations/ owns Micrate's forward SQLite schema.
• vectors/ owns canonical cross-client protocol inputs and expected results.
• spec/ owns causal Crystal behavior tests.

Development

Install the locked dependencies and run the complete core gate:

shards install --frozen
script/check

For the three-repository development loop, install the locked Node dependencies in Inkbeam Web and Inkbeam Site, then link Site to the active Web checkout without recording that local path:

cd /path/to/inkbeam-web && npm ci
cd /path/to/inkbeam-site && npm ci
npm install --no-save --package-lock=false /path/to/inkbeam-web

Start the Crystal API plus both Vite development servers from this repository:

script/dev --web /path/to/inkbeam-web --site /path/to/inkbeam-site

The public development origin is http://127.0.0.1:19135: Site owns / and /join, Web owns /notes, and Crystal owns /v1. Both frontends retain normal Vite hot reload; their internal Vite ports are development implementation details. Crystal source or migration changes rebuild and restart only the API after a successful compile, while a failed compile leaves the previous API running. Development state stays under ignored .cache/dev/ by default. Use script/dev --help to select different ports, an isolated database, or an isolated TinRelay enrollment spool. This harness is local developer composition only; production routing and process management belong to deployment.

Enroll the first local device through TinRelay, run the API service against the Inkbeam TinRelay spool, then create or read a note:

inkbeamd --database var/inkbeam.db --listen 127.0.0.1:8080 \
  --tinrelay-spool var/tinrelay/inkbeam/inbox
inkbeam auth --ship unsung-hero --endpoint http://127.0.0.1:8080
inkbeam new "Field notes" < note.md
inkbeam ls
inkbeam cat NOTE_ID

The default private configuration is ~/.config/inkbeam/device.json; --config PATH selects an isolated configuration for development. auth writes the generated Ed25519 and X25519 private keys before asking the installed tinrelay client to send only the public bootstrap document to auth@inkbeam. Repeating auth reuses that same durable device identity.

inkbeam browser [NOTE] opens the canonical hosted application. For local browser development, build inkbeam-web, pass its static output explicitly to inkbeamd --web-root PATH, and use inkbeam browser --local [NOTE]. The optional root is a generic static-client host; inkbeamd otherwise serves only the API. The core repository neither discovers a sibling build nor contains the reference client or marketing site.

Before submitting new, the CLI stores one owner-private encrypted candidate beside the device configuration. If delivery is ambiguous, repeat the same command with the same title and Markdown to retry the exact candidate; a different new is refused while that candidate remains. Only confirmed acceptance clears it. A second local new process using the same configuration is also refused while the first owns create submission.

License

Inkbeam core is available under the MIT License.