koowee / utote

µtote

A small store for small apps. Your data is encrypted on your phone, so the store keeps it but cannot read it. Use ours, or host your own.

What it does

An app keeps its data in a utote store instead of on its own server. The app says what it keeps in a short file, the manifest. You connect the app to a store. Each phone, person or agent gets its own access, and you can end each one by itself.

Collections are sealed by default. Your device encrypts each document before it leaves. The store holds only the encrypted copy and a version number. Your password and your Secret Key open the keys on a new device. The store never sees either one.

Your phone keys stay here A second person's phone own password, own key The store encrypted copies + versions no keys, cannot read them encrypted encrypted
Each phone encrypts before it sends. A second person joins with their own password. The two phones compare a short code, so the store cannot put in a key of its own.

Why use it

No server to run

An app is static files: a page, one script and a manifest. The author hosts nothing and holds nobody's data.

Host it yourself

The store is yours to pick. Use tote.koowee.org, or run your own on cheap PHP hosting or your own machine. Apps work the same with each.

The store cannot read it

Each document is encrypted on your device. A store that is broken into gives up encrypted copies, not your lists.

Share with a person

A second person joins from their own phone, with their own password. Your keys never go on their phone.

Works offline

An unlocked page keeps a copy and queues changes. It sends them when the store answers again.

Two edits do not collide

Each document has a version. If two phones change it at once, the store keeps the first and refuses the second, so no edit is lost without notice.

Access you can end

Each device has its own access, tied to that device's key. End one lost phone, and the others keep working.

How to use it

Use an app · someone shared it with you

  1. Open the invite link on your phone. It works once, for 24 hours. The user guide has each screen.
  2. Check the store's name that the page shows. Accept only a store you expect.
  3. Make your own password. Save the kit that the page shows: your account and your Secret Key. The page shows them once.
  4. To join a shared household, show your code to a phone that is already in it. Then type or scan the code it shows back.

Write an app · two files and a manifest

Put adapter.js and unlock.js beside your page. They have no dependencies and no build step. Declare your collections:

{
  "app": "notes",
  "schema": 1,
  "needs": { "docs": {
    "notes":   { "key": "notes/{id}" },
    "keyring": { "key": "{kind}/{who}/{what}", "clear": ["pub", "epk"] }
  } }
}

Then connect, unlock and use the data:

import { Store } from './adapter.js';
import { unlock } from './unlock.js';

const store = await Store.fromLocation('tote.koowee.org', {
  offline: true,
  confirmInvite: host => askPerson(`Connect to the store at ${host}?`),
});
await unlock(store, { collections: { notes: {} }, ui: { askSecret } });

const notes = store.docs('notes');
await notes.set('notes/first', { text: 'hello' }, { ifVersion: 0 });   // create only
const doc = await notes.get('notes/first');                             // { exists, version, data() }

The app-author guide covers conflicts, offline writes, sharing and errors. The security model says what a hostile store can and cannot do.

Run a store · see Host your own

You do not need ours. Any server that passes the spec's conformance suite works with every app.

Host your own

A store is one small server. Pick the one that fits where you can run things. The same conformance suite runs against each, so an app does not care which one it talks to.

ServerRuns onHolds
utote.phpShared PHP hosting with MySQL or MariaDB. tote.koowee.org runs it.Documents only. It is a relay: it keeps encrypted copies and passes them on.
utotepyYour own machine, with Python and DuckDBDocuments, settings, files and optional SQL, with an MCP server for agents
utote-node plannedNode.js, where Python is hard to installNot decided yet: a full server or a relay. There is no code yet.

utote.php on PHP hosting

# copy the relay files to your host, then on the host:
php relay.php schema                                  # make the tables
php relay.php init me/notes/main manifest.json        # add an app
php relay.php invite me/notes/main write https://notes.example/   # a link for one device

utotepy on your own machine

uv sync
DS_ROOT_TOKEN=change-me DS_ROOT_NS=home DS_DATA_DIR=./data \
  .venv/bin/python -m utotepy                         # listens on 127.0.0.1:8787

Put a proxy with TLS in front of it. The developer guide lists every setting.

Coming

A DuckDB extension planned

Attach a store to DuckDB and query it with SQL, outside any app. Encrypted data opens on the machine where DuckDB runs. The store still never sees a key. It reads first. Writes come in a second version. There is no code yet.

INSTALL tote; LOAD tote;
ATTACH 'https://tote.koowee.org/me/notes/main' AS notes (TYPE tote, KEY_FILE '~/.config/utote/laptop.jwk');
SELECT key, body->>'$.text' AS text FROM notes.docs.notes;

A later add-on for utote.js will let a page hand its decrypted documents to DuckDB-Wasm in the browser, to read. Read the DuckDB roadmap.

utote-node planned

A store server for Node.js. See Host your own.

In use

Both are small, and both are ours.

Where it is today

utote is early. Read this before you keep anything in it.

Words on this page

store
The server that keeps an app's data
manifest
The short file in which an app says what it keeps
sealed
A collection whose documents are encrypted on your device before the store gets them. This is the default.
Secret Key
A long code that your device makes. With your password, it opens your keys on a new device.
kit
Your account name and Secret Key, shown once when you make an account