Skip to content
This repository was archived by the owner on Nov 1, 2026. It is now read-only.

Latest commit

 

History

History
230 lines (179 loc) · 13.6 KB

PROTOCOL.md

File metadata and controls

230 lines (179 loc) · 13.6 KB

Rem, the Looscid protocol (version 0)

Looscid runs on Rem. This is the public spec: any app can be a Rem client, not just the Looscid app. Everything here is what the server in this repo actually does.

The name lives in one place in code (PROTOCOL in public/js/rem-core.js): name is what people read, key is the envelope field, base is the API path, live is the WebSocket path.

1. The idea

  • Key-first identity. Your LooscidID is a secp256k1 key pair, the same kind Nostr uses. Any Nostr key works as a LooscidID, and every LooscidID has an npub. The secret key stays on your device.
  • Everything is a signed object. A Dream, a like, a follow, a Chat: each is a small JSON object signed by the LooscidID that made it. The server checks every signature and cannot make or change objects for you.
  • Local-first, syncs through the Looscid server. Clients keep their own copy and work offline. The home server is the meeting spot: it keeps copies so friends get your things while you are away, and so a new device gets everything back (GET /sync).
  • A home is accountable. Invite-only, 13+, blocks that work both ways, reports and moderators.
  • Accessibility is in the protocol. Images without alt text are refused by the server. Content warnings and "how to read this aloud" are fields, not hacks.

2. Objects

{ "rem": 0,
  "type": "dream",
  "by": "<32-byte public key, hex>",
  "at": 1761948000000,
  "body": { "text": "hello", "audience": "public" },
  "id": "<sha256 hex>",
  "sig": "<64-byte BIP-340 Schnorr signature, hex>" }
  • id = sha256 of the UTF-8 bytes of canonical([0, by, at, type, body]).
  • canonical JSON: like JSON.stringify, but the keys of every object (at every depth) are sorted, no spaces, undefined values left out. Arrays keep their order.
  • sig = BIP-340 Schnorr signature of the 32 bytes of id, by the key by (same math as Nostr events).
  • at is Unix time in milliseconds and must be within 10 minutes of the server's clock (except for /import, below).
  • Max 64 KB per object.

Types and bodies

type body notes
profile { name, bio, pronouns, avatar?: media, chats_from: "mutuals"|"nobody" } newest at wins
dream { text, cw?, speak?, lang?, audience: "public"|"followers", reply_to?, quote?, media?: [media], poll?: { options: [2-4 strings], closes_at }, tags?, post_at? } post_at = scheduled (up to 30 days)
redream { of: dreamId } public Dreams only
react { of: dreamId, r: "like" } v0: like only
edit { of: dreamId, text, cw?, speak? } your own Dreams; history kept
delete { of: objectId } a Dream, react, redream, vote or Chat of yours
follow / unfollow { who: pubkey }
block / unblock { who: pubkey } private; also removes follows both ways
vote { of: dreamId, choice: index } one vote per poll, can change until it closes
chat { to: pubkey, box: "<NIP-44 v2 payload>" } mutuals only, see Chats
report { of: dreamId | pubkey | chatId, reason, note?, evidence? } reasons: spam, bullying, sexual, self_harm, violence, other
role_answer { invite: roleInviteId, accept: true|false } answers an admin/moderator invite
leave {} deletes your account and everything you made on this home

media = { url, alt, mime?, w?, h? }. url must be an image uploaded to this home (POST /media) by you. alt is required (1-1500 characters). Limits: text 1000 characters, content warning 200, 4 images, 5 MB per image.

Accessibility fields

  • alt is required on every image. Without it the server answers 422 {"code":"alt_required"}.
  • cw is a content warning. Clients show the warning first and hide the rest until it is opened.
  • speak is how the Dream should be read aloud. If it is missing and the text has links or emoji runs, the server adds speak_hint to items (links become "link to site", runs of 3+ same emoji are counted).
  • Events carry names a client can attach sounds (earcons) to: dream.new, reply.new, like.new, redream.new, follow.new, chat.new, alert.mention, role.invite, role.answer.
  • Clients should never move focus or insert above the reader when something arrives live: show "3 new Dreams" and let the person choose.

3. HTTP API

Base: https://<home>/rem/v0. JSON in and out. CORS is open (*) so any web client can connect. Sign-in uses a Bearer token, never cookies. Errors are { "ok": false, "code": "...", "message": "..." }; message is plain English that a screen reader can read as-is.

Discovery: GET /.well-known/looscid (and GET /rem/v0/) gives the protocol, limits, invite rules and paths.

Joining and signing in

  • POST /join { invite, handle, name?, pubkey, age_ok: true, sig } → { token, expires, me } sig signs the text rem-join:<home>:<INVITE>:<handle> (sha256 of the UTF-8 text, Schnorr-signed). Handles: 2-20 of a-z, 0-9, _. The owner's handle is reserved (see Owner).
  • POST /auth/challenge { pubkey } → { nonce, sign }
  • POST /auth/login { pubkey, nonce, sig } → { token, expires, me } where sig signs the text in sign (rem-login:<home>:<nonce>). Tokens last 30 days; the server keeps only their hash.
  • POST /auth/logout, GET /me

Writing

  • POST /objects a signed object → { ok: true, id, seq } (must be signed by the signed-in LooscidID).
  • POST /media the image bytes as the body, Content-Type: image/jpeg|png|webp, alt text in the X-Rem-Alt header (URL-encoded); or multipart/form-data with file and alt. → { media: { url, mime, alt, w, h } }. The server keeps only the image data: location (GPS), camera, dates, XMP and comments are removed. JPEG keeps only its orientation.

Reading

Lists are paged: ?before=<next>&limit=20 → { items, next }.

  • GET /feed/dreamline Dreams and ReDreams from you and people you follow, newest first, no algorithm.
  • GET /feed/discover public Dreams on this home.
  • GET /objects/:id, GET /dreams/:id/thread, GET /dreams/:id/history (original + edits).
  • GET /dreamors/:handle-or-pubkey and /dreamors/:handle-or-pubkey/dreams.
  • GET /notifications (same as /alerts), POST /alerts/seen.
  • GET /chats, GET /chats/:pubkey (signed, encrypted Chat objects; decrypt on the device).
  • GET /search?q=&type=all|dreams|dreamors, GET /trending (tags and most-active public Dreams, 24 hours).
  • GET /invites, POST /invites → { code, invite_link }.
  • GET /sync?since=<cursor> every object you made, plus Chats and deletes addressed to you, oldest first → { objects, cursor, more }. This is how a new device gets everything back: sign in, call /sync from 0.
  • GET /export the same, as one download.

Items look like { id, by: { pubkey, npub, handle, name, ... }, at, text, cw, speak, speak_hint, media, link, poll, counts: { replies, redreams, likes }, me: { liked, redreamed }, ... }.

Reads need sign-in on this home (it is members-only) unless the home sets public_read.

Importing Dreams you already have (opt-in)

POST /import { objects: [signed dream objects] } (up to 200 per request). For people who used Looscid on their device before joining the server. Nothing is uploaded unless the person chooses it in their app.

  • Each Dream must be signed by the signed-in LooscidID and keeps its original at (any past time since 2020).
  • Same id already on the server = skipped (safe to retry).
  • Replies keep their thread: a Dream with reply_to (or quote) is imported only when that Dream is already on the server (send parents first; one request is handled in order). Otherwise it comes back in refused with code parent_missing and stays on the device. It is never turned into a loose Dream.
  • Imported Dreams appear on the profile in their original time order; they are not pushed into anyone's Dreamline as new.
  • A Dream whose images have no alt text is not dropped silently: it comes back in needs_alt and stays in GET /import/flags until the person adds alt text, signs again and imports again, or dismisses it (POST /import/flags/dismiss { id }).
  • Images must be uploaded with /media first (so the server can check and clean them).

Answer: { imported: [ids], skipped: [...], needs_alt: [{ id, images, message }], refused: [{ id, code, message }] }.

Backup file (.looscid)

The Looscid app and this web client save and restore the same backup file (public/js/looscid-backup.js): your profile, Dreams, replies, Chats, likes, follows, settings and your LooscidID key in one file, locked with a passcode you choose. Outside: { "looscid_backup": 1, "kdf": { "name": "PBKDF2", "hash": "SHA-256", "iterations": 600000, "salt" }, "cipher": { "name": "AES-GCM", "iv" }, "data" } (base64; AES-GCM 256-bit with additional data looscid-backup-v1). Inside: { looscid_backup_data: 1, from: "app"|"home", key: { nsec, pubkey }, profile, server, dreams, rem_objects, app, home }. Nothing is readable without the passcode, and nobody can recover a forgotten one. Restoring on a home signs in with the key, imports the signed Dreams (/import, original times) and signs follows and likes again with the same key.

4. The live stream (WebSocket)

wss://<home>/rem/v0/live. Send {"op":"auth","token":"..."} first (within 15 s).

Client → server:

  • {"op":"sub","streams":["dreamline","discover","alerts","chats"]} (all four by default)
  • {"op":"send","ref":"x","object":{...}} same as POST /objects, answered by ok or err with the same ref
  • {"op":"ping"}

Server → client:

  • {"op":"hello","me":{...},"unseen_alerts":3}
  • {"op":"item","stream":"dreamline"|"discover","event":"dream.new"|"reply.new"|"redream.new","item":{...}}
  • {"op":"update","item":{...}} (an edit, a link card arrived, a poll changed), {"op":"remove","id":"..."}
  • {"op":"alert","event":"like.new",...,"alert":{...}}
  • {"op":"chat","event":"chat.new","object":{...}}, {"op":"chat_deleted","id":"..."}
  • {"op":"ok",...}, {"op":"err","code","message"}, {"op":"pong"}

The server pings every 30 seconds. Reconnect with a short delay if the line drops; then fetch the lists again.

5. Chats

  • Only between mutuals (you both follow each other), never with someone you blocked or who blocked you, and not if the other person turned Chats off.
  • End-to-end encrypted with NIP-44 v2 (the same as Nostr): conversation key from ECDH of the two LooscidIDs, ChaCha20 + HMAC-SHA256, padded.
  • The plaintext inside box is itself a signed object: { type: "chat_message", body: { to, text } } signed by the sender. So a person who reports a Chat can attach it as evidence, and moderators can check it is real without being able to read anyone's Chats.
  • The server stores the locked box so it arrives when the other person is offline. It can see who chats with whom and when, not what they say.

6. Safety on a home

  • Invite-only. Each code makes one account. Members earn 3 invites after 7 days (both numbers are settings); the owner, admins and moderators can make more. The home remembers who invited whom.
  • 13+ only (a checkbox). No email, phone, birthday or location is asked for or stored. IP addresses are used only in memory for rate limits and never written down.
  • Blocks work both ways: no seeing each other's Dreams, replies, follows, mentions or Chats. They are not told.
  • Rate limits: 20 Dreams an hour for accounts newer than 7 days (60 after), 50 follows a day, 30 uploads an hour.
  • Reports go to the moderators' queue.

Roles

owner (one per home), admin, mod, member. Roles are offered, never forced:

  1. The owner (any role) or an admin (moderator only) calls POST /mod/action { action: "invite_role", target: handle-or-pubkey, role: "admin"|"mod" }.
  2. The person gets a role_invite notification (live, and in /notifications) with the invite id.
  3. They answer with a signed role_answer { invite, accept }. Accepting grants the role.
  4. The owner can take a role away: { action: "revoke_role", target }. Everything is in GET /mod/log.

Moderation (owner, admins, moderators)

  • GET /mod/reports?status=open|resolved, GET /mod/stats, GET /mod/tree (members and who invited them), GET /mod/log.
  • POST /mod/action { target, action, note? } with action: hide / unhide (a Dream), suspend / unsuspend (an account), revoke_invites, resolve / reopen (a report), invite_role, revoke_role, remove_account (owner only).

Owner

The owner's handle (default 2three1y, a setting) is reserved. Nobody gets it by asking: a join with that handle and no owner code is only written down as a pending claim. The person running the home holds an owner code (the server keeps only its hash) and binds the handle to a LooscidID:

  • GET /admin/owner-claims (header X-Rem-Owner-Code) lists pending claims with their npubs.
  • POST /admin/owner { pubkey: npub-or-hex, name? } (same header) makes that LooscidID the owner. If it is not a member yet, the account is created. replace: true moves ownership to a new key (for a lost key).
  • Joining with the owner code as the invite and the owner handle also works, once.
  • GET /admin/backup (owner token or the X-Rem-Backup-Key header): a .tar.gz with a consistent copy of the database (VACUUM INTO) and all media.

7. Nostr

A LooscidID is a Nostr key, so the same person can use both. The bridge (importing old Looscid Nostr notes, mirroring public Dreams out, a read-only Nostr relay on the home) is planned for later and is off in v0.

8. Later

Federation between homes (/rem/v1/inbox, signed by the sending home), circles, private accounts with follow requests, mutes, audio Dreams, moving an account to a new key, a Nostr bridge.