# 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](https://mise.jdx.dev/): ```sh 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): ```sh cargo run -- user create silen cargo run -- user reset silen # new generated password; the old one stops working ``` Open , 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: ```sh cargo run -- token create laptop # read + write cargo run -- token create dashboard --read-only cargo run -- token list cargo run -- token revoke ``` ## Configuration | Variable | Default | Meaning | |----------|---------|---------| | `BIND_ADDRESS` | `127.0.0.1` | Address the server listens on | | `PORT` | `8080` | Port the server listens on | | `DB_PATH` | `cairn.db` | SQLite database file | | `CAIRN_URL` | `https://cairn.silenlocatelli.ch` | Server 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_LOG` | `info` | Log 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 `. - 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 ```sh 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 # shows metadata and files cairn edit --title "New title" cairn edit --content-file notes.md # or `-` for stdin cairn edit --meta source=phone --meta place=lisbon # replaces all metadata cairn tag reference web cairn untag web cairn attach photo.jpg other.pdf cairn fetch --out photo.jpg # or no --out to pipe to stdout cairn detach cairn rm # 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": "..."}`. | Method | Path | Scope | Notes | |--------|------|-------|-------| | `GET` | `/me` | any | The token in use | | `GET` | `/items` | read | `q`, `tag`, `meta.`, `sort`, `order`, `limit`, `offset` | | `POST` | `/items` | write | `{"title"?, "content"?, "tags"?, "metadata"?}` → `201` | | `GET` | `/items/{id}` | read | Includes `metadata` and `attachments` | | `PATCH` | `/items/{id}` | write | `{"title"?, "content"?, "metadata"?}`; metadata replaces the whole object | | `DELETE` | `/items/{id}` | write | `204`; also deletes its attachments | | `POST` | `/items/{id}/tags` | write | `{"tags": [...]}` adds tags | | `DELETE` | `/items/{id}/tags/{tag}` | write | Removes one tag | | `POST` | `/items/{id}/attachments?filename=…` | write | Raw file bytes as the body → `201` | | `GET` | `/attachments/{id}` | read | The file's bytes | | `DELETE` | `/attachments/{id}` | write | `204` | | `GET` | `/tags` | read | Tags with counts | | `GET` | `/tokens` | write | Token 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.=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. ```sh # 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: ```sh 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 ```sh mise run test # cargo test mise run verify # fmt check, clippy (pedantic), tests ```