Skip to content

cairn

An archive for things you want to remember. Paste text or pictures in the browser, or save, search, tag, and change items from the CLI or over an HTTP API that agents can call. Everything, including the files, lives in one SQLite database.

Built with the same stack as twig (~/twig): Rust, Actix-web, maud, and rusqlite (bundled), with personal access tokens modelled on twig's.

Quick start

With mise:

mise run run            # cargo run -- serve, on 127.0.0.1:8080, DB in ./cairn.db

Create a sign-in (the password is generated and printed once):

cargo run -- user create silen
cargo run -- user reset silen             # new generated password; the old one stops working

Open http://127.0.0.1:8080, sign in, and paste anything. Pictures can be pasted straight from the clipboard, or chosen with the file picker. Change your password on the Account page.

API and CLI access uses tokens. Create them on the Tokens page, or on the command line:

cargo run -- token create laptop          # read + write
cargo run -- token create dashboard --read-only
cargo run -- token list
cargo run -- token revoke <id>

Configuration

VariableDefaultMeaning
BIND_ADDRESS127.0.0.1Address the server listens on
PORT8080Port the server listens on
DB_PATHcairn.dbSQLite database file
CAIRN_URLhttps://cairn.silenlocatelli.chServer the CLI talks to. Set it to http://127.0.0.1:8080 for a local server
CAIRN_TOKEN—Access token the CLI sends
RUST_LOGinfoLog filter

Items, metadata, and files

An item has a title, text content, tags, a metadata object, and any number of attachments:

  • Text can be empty if the item has a title or files.
  • Metadata is a JSON object with identifier keys (letters, digits, _, -), for example {"source": "slack", "priority": "2"}. Filters compare values as text.
  • Attachments are stored as BLOBs in the database, up to 25 MiB each. The type is detected from the file's bytes, never from its name. Images display inline; everything else downloads, with nosniff set, so an uploaded HTML file cannot run on this origin.
  • Filenames are searchable, so cairn search packing finds packing-list.txt.

Access tokens

  • Format: cairnt_ followed by 64 hex characters.
  • Stored as a SHA-256 hash, with the last four characters kept for display.
  • Scopes: read (list, search, get, download) and write (create, edit, delete, tag, upload). write implies read. --read-only creates a read-only token.
  • Send as Authorization: Bearer <token>.
  • Revoking a token takes effect on the next request.

Accounts and sessions

  • Sign-in is a username and password. Passwords are hashed with argon2. Usernames are case-insensitive; user-chosen passwords are at least 12 characters.
  • Signing in creates a server-side session. The browser holds a random cairns_ secret in an HttpOnly, SameSite=Strict cookie, and the server stores only its hash. Sessions last 30 days, and signing out deletes the session.
  • A signed-in person has full access to the archive. Tokens are how scripts and agents get in, and the Tokens page lists and revokes them.
  • All accounts share one archive. There is no per-user ownership of items.

CLI

export CAIRN_TOKEN=cairnt_…
cairn add --title "Lifetimes" --tag rust "Lifetimes tie references to scopes."
cairn add --tag travel --meta source=camera --file beach.png   # a picture
some-command | cairn add --tag logs                           # text from stdin
cairn ls --tag rust --sort created --order asc --limit 20
cairn ls --meta source=camera                                  # metadata filter
cairn search borrow checker                    # all words must match; prefixes too
cairn get <id>                                 # shows metadata and files
cairn edit <id> --title "New title"
cairn edit <id> --content-file notes.md        # or `-` for stdin
cairn edit <id> --meta source=phone --meta place=lisbon   # replaces all metadata
cairn tag <id> reference web
cairn untag <id> web
cairn attach <id> photo.jpg other.pdf
cairn fetch <file-id> --out photo.jpg          # or no --out to pipe to stdout
cairn detach <file-id>
cairn rm <id>                                  # also deletes its files
cairn tags
cairn whoami

cairn add prints only the new id, so it works in scripts: id=$(cairn add --tag todo "buy batteries").

HTTP API

Base path /api/v1. JSON in and out, except uploads and downloads, which use raw bytes. Errors are {"error": "..."}.

MethodPathScopeNotes
GET/meanyThe token in use
GET/itemsreadq, tag, meta.<key>, sort, order, limit, offset
POST/itemswrite{"title"?, "content"?, "tags"?, "metadata"?} → 201
GET/items/{id}readIncludes metadata and attachments
PATCH/items/{id}write{"title"?, "content"?, "metadata"?}; metadata replaces the whole object
DELETE/items/{id}write204; also deletes its attachments
POST/items/{id}/tagswrite{"tags": [...]} adds tags
DELETE/items/{id}/tags/{tag}writeRemoves one tag
POST/items/{id}/attachments?filename=…writeRaw file bytes as the body → 201
GET/attachments/{id}readThe file's bytes
DELETE/attachments/{id}write204
GET/tagsreadTags with counts
GET/tokenswriteToken metadata; never secrets
  • q is full-text search over title, content, tags, and filenames. Each word is matched as a prefix and all words must match. Without sort, results are ranked by relevance when q is given and by last update otherwise.
  • meta.<key>=value filters on a top-level metadata key. Repeat it to require several.
  • sort is relevance, created, updated, or title. order is asc or desc.
  • Tags are lowercased, # is dropped, inner spaces become -, and only letters, digits, -, _, and . are allowed (up to 64 characters).
  • A new item needs text or a title. If title is omitted, it comes from the first non-empty line of content.
  • Text content is limited to 10 MiB and each file to 25 MiB.
# create an item
curl -s -X POST http://127.0.0.1:8080/api/v1/items \
  -H "Authorization: Bearer $CAIRN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"content":"remember this","tags":["agent"],"metadata":{"source":"agent"}}'

# attach a picture to it (the id comes from the response above)
curl -s -X POST "http://127.0.0.1:8080/api/v1/items/$ID/attachments?filename=beach.png" \
  -H "Authorization: Bearer $CAIRN_TOKEN" --data-binary @beach.png

# search
curl -s "http://127.0.0.1:8080/api/v1/items?q=remember&meta.source=agent" \
  -H "Authorization: Bearer $CAIRN_TOKEN"

Web

  • / — paste box with title, text, files, tags, and metadata, plus recent items
  • /search?q=…&tag=… — search results
  • /items/{id} — view, edit, tag, attach files, or delete an item
  • /attachments/{id} — a file, shown inline if it is an image

The Tokens page creates and revokes API tokens. The Account page changes your password.

Deploying

Run behind a reverse proxy that terminates TLS, and bind the app to loopback (BIND_ADDRESS=127.0.0.1). Keep DB_PATH on persistent storage. The session cookie does not set Secure, so it should only ever travel over HTTPS.

Create the first account inside the running container. The password is printed once:

ino once exec cairn.silenlocatelli.ch cairn user create silen

Sign in at the app with that password, then create API tokens on the Tokens page.

Development

mise run test     # cargo test
mise run verify   # fmt check, clippy (pedantic), tests