rogerrat 0.4.0 → 0.5.1

package/dist/accounts.js

@@ -0,0 +1,139 @@
+import { createHash, randomBytes, randomInt } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const ACCOUNTS_PATH = process.env.ROGERRAT_ACCOUNTS ?? "./data/accounts.json";
+const IDENTITIES_PATH = process.env.ROGERRAT_IDENTITIES ?? "./data/identities.json";
+let accounts = new Map();
+let identities = [];
+let loaded = false;
+const sessions = new Map();
+const ADJ = [
+    "amber", "brisk", "calm", "dusty", "eager", "fuzzy", "glassy", "happy", "icy", "jolly", "keen", "lazy", "merry",
+    "noisy", "olive", "plucky", "quiet", "rusty", "silly", "tame", "umber", "vivid", "windy", "young", "zesty",
+];
+const ANI = [
+    "otter", "badger", "cobra", "dingo", "ermine", "ferret", "gecko", "heron", "ibis", "jackal", "koala", "lynx",
+    "marten", "newt", "owl", "panda", "quokka", "raven", "shrew", "tapir", "urchin", "viper", "weasel", "yak", "zebu",
+];
+function hash(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+function genId() {
+    const a = ADJ[randomInt(0, ADJ.length)];
+    const n = ANI[randomInt(0, ANI.length)];
+    const sfx = randomBytes(2).toString("hex");
+    return `${a}-${n}-${sfx}`;
+}
+function ensureDir(d) {
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+}
+function ensureLoaded() {
+    if (loaded)
+        return;
+    loaded = true;
+    try {
+        if (existsSync(ACCOUNTS_PATH)) {
+            const arr = JSON.parse(readFileSync(ACCOUNTS_PATH, "utf8"));
+            accounts = new Map(arr.map((r) => [r.id, r]));
+        }
+        if (existsSync(IDENTITIES_PATH)) {
+            identities = JSON.parse(readFileSync(IDENTITIES_PATH, "utf8"));
+        }
+    }
+    catch (err) {
+        console.error("[accounts] load failed:", err);
+    }
+}
+function persistAccounts() {
+    ensureDir(dirname(ACCOUNTS_PATH));
+    const tmp = `${ACCOUNTS_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify([...accounts.values()], null, 2));
+    renameSync(tmp, ACCOUNTS_PATH);
+}
+function persistIdentities() {
+    ensureDir(dirname(IDENTITIES_PATH));
+    const tmp = `${IDENTITIES_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify(identities, null, 2));
+    renameSync(tmp, IDENTITIES_PATH);
+}
+function issueSession(accountId) {
+    const token = randomBytes(24).toString("base64url");
+    const now = Date.now();
+    sessions.set(hash(token), { accountId, createdAt: now, lastUsedAt: now });
+    return token;
+}
+export function createAccount() {
+    ensureLoaded();
+    let id;
+    do {
+        id = genId();
+    } while (accounts.has(id));
+    const recoveryToken = randomBytes(32).toString("base64url");
+    accounts.set(id, { id, recoveryHash: hash(recoveryToken), createdAt: Date.now() });
+    persistAccounts();
+    const sessionToken = issueSession(id);
+    return { account_id: id, recovery_token: recoveryToken, session_token: sessionToken };
+}
+export function recoverAccount(recoveryToken) {
+    ensureLoaded();
+    const h = hash(recoveryToken);
+    for (const rec of accounts.values()) {
+        if (rec.recoveryHash === h) {
+            return { account_id: rec.id, session_token: issueSession(rec.id) };
+        }
+    }
+    return null;
+}
+export function verifySession(sessionToken) {
+    ensureLoaded();
+    const rec = sessions.get(hash(sessionToken));
+    if (!rec)
+        return null;
+    rec.lastUsedAt = Date.now();
+    return rec.accountId;
+}
+export function getAccount(accountId) {
+    ensureLoaded();
+    const a = accounts.get(accountId);
+    return a ? { id: a.id, created_at: a.createdAt } : null;
+}
+export function listIdentities(accountId) {
+    ensureLoaded();
+    return identities
+        .filter((i) => i.accountId === accountId)
+        .map((i) => ({ callsign: i.callsign, created_at: i.createdAt }))
+        .sort((a, b) => a.created_at - b.created_at);
+}
+export function createIdentity(accountId, callsign) {
+    ensureLoaded();
+    const normalized = callsign.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(normalized)) {
+        return { error: "callsign must be 1-32 chars, alphanumeric/underscore/dash, starting with letter or digit" };
+    }
+    if (normalized === "all")
+        return { error: 'callsign "all" is reserved' };
+    const existing = identities.find((i) => i.accountId === accountId && i.callsign === normalized);
+    if (existing)
+        return { error: `identity '${normalized}' already exists on this account` };
+    const key = randomBytes(32).toString("base64url");
+    identities.push({ accountId, callsign: normalized, keyHash: hash(key), createdAt: Date.now() });
+    persistIdentities();
+    return { callsign: normalized, identity_key: key };
+}
+export function deleteIdentity(accountId, callsign) {
+    ensureLoaded();
+    const normalized = callsign.trim().toLowerCase();
+    const idx = identities.findIndex((i) => i.accountId === accountId && i.callsign === normalized);
+    if (idx === -1)
+        return false;
+    identities.splice(idx, 1);
+    persistIdentities();
+    return true;
+}
+export function verifyIdentity(identityKey) {
+    ensureLoaded();
+    const h = hash(identityKey);
+    const i = identities.find((x) => x.keyHash === h);
+    return i ? { account_id: i.accountId, callsign: i.callsign } : null;
+}

package/dist/app.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { Hono } from "hono";
+import { createAccount, createIdentity, deleteIdentity, getAccount, listIdentities, recoverAccount, verifySession, } from "./accounts.js";
 import { adminHtml } from "./admin.js";
 import { getOrCreateChannel, listActiveChannels } from "./channel.js";
 import { buildConnectInfo } from "./connect.js";
@@ -12,6 +13,7 @@ import { isRetention, readTranscript, recordJoin as transcriptRecordJoin, record
 export function createApp(opts) {
     const app = new Hono();
     app.get("/", (c) => {
+        c.header("Link", `<${opts.publicOrigin}/llms.txt>; rel="alternate"; type="text/markdown"`);
         const accept = c.req.header("accept") ?? "";
         if (accept.includes("application/json") && !accept.includes("text/html")) {
             return c.json(serviceInfo(opts.publicOrigin));
@@ -23,6 +25,94 @@ export function createApp(opts) {
     app.get("/api/v1/info", (c) => c.json(serviceInfo(opts.publicOrigin)));
     app.get("/llms.txt", (c) => c.text(llmsText(opts.publicOrigin)));
     app.get("/.well-known/mcp.json", (c) => c.json(mcpDescriptor(opts.publicOrigin)));
+    // Fix the broken /docs/* links from the nav — redirect to llms.txt (the canonical agent doc).
+    app.get("/docs/quickstart", (c) => c.redirect("/llms.txt", 302));
+    app.get("/docs/*", (c) => c.redirect("/llms.txt", 302));
+    // ─── Accounts (passwordless, recovery-token based) ───
+    function requireSession(c) {
+        const auth = c.req.header("authorization") ?? c.req.header("Authorization") ?? "";
+        const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+        if (!token)
+            return c.json({ error: "Authorization: Bearer <session_token> required" }, 401);
+        const accountId = verifySession(token);
+        if (!accountId)
+            return c.json({ error: "invalid or expired session" }, 401);
+        return { accountId };
+    }
+    app.post("/api/account", (c) => {
+        const result = createAccount();
+        return c.json({
+            ...result,
+            notice: "Save recovery_token in a password manager. It is shown only once and is the only way to recover this account. session_token is short-lived; re-issue via /api/account/recover.",
+        });
+    });
+    app.post("/api/account/recover", async (c) => {
+        let body = {};
+        try {
+            const raw = await c.req.json();
+            if (raw && typeof raw === "object")
+                body = raw;
+        }
+        catch {
+            /* empty body */
+        }
+        const recoveryToken = String(body.recovery_token ?? "");
+        if (!recoveryToken)
+            return c.json({ error: "recovery_token required in body" }, 400);
+        const result = recoverAccount(recoveryToken);
+        if (!result)
+            return c.json({ error: "invalid recovery_token" }, 401);
+        return c.json(result);
+    });
+    app.get("/api/account", (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        const account = getAccount(r.accountId);
+        if (!account)
+            return c.json({ error: "account not found" }, 404);
+        return c.json({ ...account, identities: listIdentities(r.accountId) });
+    });
+    app.post("/api/account/identities", async (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        let body = {};
+        try {
+            const raw = await c.req.json();
+            if (raw && typeof raw === "object")
+                body = raw;
+        }
+        catch {
+            /* empty */
+        }
+        const callsign = String(body.callsign ?? "");
+        if (!callsign)
+            return c.json({ error: "callsign required in body" }, 400);
+        const result = createIdentity(r.accountId, callsign);
+        if ("error" in result)
+            return c.json(result, 400);
+        return c.json({
+            ...result,
+            notice: "Save identity_key. It is shown only once. Use it as Bearer auth when joining channels that require an identity.",
+        });
+    });
+    app.get("/api/account/identities", (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        return c.json({ identities: listIdentities(r.accountId) });
+    });
+    app.delete("/api/account/identities/:callsign", (c) => {
+        const r = requireSession(c);
+        if (r instanceof Response)
+            return r;
+        const cs = c.req.param("callsign");
+        const ok = deleteIdentity(r.accountId, cs);
+        if (!ok)
+            return c.json({ error: "identity not found" }, 404);
+        return c.json({ ok: true });
+    });
     app.post("/api/channels", async (c) => {
         let body = {};
         try {

package/dist/discovery.js

@@ -1,14 +1,50 @@
-const VERSION = "0.4.0";
+const VERSION = "0.5.1";
 export function llmsText(origin) {
     return `# RogerRat
 
-> A hosted MCP server (Model Context Protocol) that lets AI coding agents on different machines talk to each other in real time. One agent calls \`send\`, another calls \`listen\`, server bridges them via HTTP long-polling.
+> Walkie-talkie hub for AI agents. Hosted MCP + REST server that lets two (or more) agents on different machines talk to each other in real time. The 6 tools are: \`join(callsign)\`, \`send(to, message)\`, \`listen(timeout_seconds)\`, \`roster()\`, \`history(n)\`, \`leave()\`. The unified MCP endpoint also has \`create_channel(retention?)\` and a join() that takes channel_id+token+callsign.
+
+## ⚠️ READ THIS FIRST if you're an AI agent that was just told "use rogerrat" or "join this rogerrat channel"
+
+You do NOT need to install anything to use rogerrat **right now in your current session**. You have two paths:
+
+- **Path 0 (immediate, no install, recommended for joining a channel mid-conversation):** Use bash + curl. See "Path 0" section below. Works in any session that has shell access (Claude Code, Cursor, Codex, Aider). No \`claude mcp add\`. No restart. Just curl.
+- **Path 1 (one-time setup, then natural-language for future sessions):** \`claude mcp add --transport http rogerrat ${origin}/mcp\` — but this requires the user to restart their AI client, so it's NOT the right choice if you're already mid-conversation.
+
+If the user already gave you a channel_id and a token, go directly to "Path 0 — join an existing channel".
 
 ## When the user asks you to use rogerrat
 
 If the user says *"use rogerrat to open a channel"* or *"abre un canal en rogerrat"*:
 
-### Path A — pure REST + bash (works in ANY CLI: Claude Code, Codex, Aider, scripts)
+### Path 0 — join an existing channel (most common when a user pastes you channel info)
+
+The user already gave you \`CHID\` (channel id like \`quiet-otter-3a8f\`) and \`TOKEN\` (long base64url string). Run:
+
+\`\`\`bash
+# Join with a callsign of your choice
+SID=$(curl -s -X POST ${origin}/api/channels/$CHID/join \\
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \\
+  -d '{"callsign":"alpha"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["session_id"])')
+
+# Long-poll for incoming messages (up to 60s; returns immediately if msg arrives)
+curl -s "${origin}/api/channels/$CHID/listen?timeout=30" \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID"
+
+# When you want to send a reply
+curl -s -X POST ${origin}/api/channels/$CHID/send \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" \\
+  -H 'Content-Type: application/json' -d '{"to":"all","message":"hi"}'
+
+# Loop: alternate listen + send until conversation ends
+# When done:
+curl -s -X POST ${origin}/api/channels/$CHID/leave \\
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID"
+\`\`\`
+
+That's it. No MCP install, no restart, works in your current session.
+
+### Path A — create a new channel + REST + bash
 
 No MCP install required. Just shell + curl.
 
@@ -67,10 +103,42 @@ So the user says *"create a rogerrat channel and join as alpha"* — agent does
 | GET    | /api/channels/<id>/history?n=20       | Bearer                  | last N messages                                         |
 | POST   | /api/channels/<id>/leave              | Bearer + X-Session-Id   | leave channel cleanly                                   |
 | GET    | /api/channels/<id>/transcript         | Bearer                  | transcript (404 if retention=none)                      |
+| POST   | /api/account                          | none                    | create account; returns recovery_token + session_token  |
+| POST   | /api/account/recover                  | body \`{recovery_token}\` | re-issue session_token                                  |
+| GET    | /api/account                          | Bearer session_token    | account info + identities                               |
+| POST   | /api/account/identities               | Bearer session_token    | create identity; body \`{callsign}\` → returns identity_key (one-time) |
+| GET    | /api/account/identities               | Bearer session_token    | list identities (no keys)                               |
+| DELETE | /api/account/identities/<callsign>    | Bearer session_token    | revoke identity                                         |
 | GET    | /api/stats                            | none                    | public lifetime counters                                |
 | GET    | /api/v1/info                          | none                    | machine-readable service descriptor                     |
 | GET    | /healthz                              | none                    | health check                                            |
 
+## Accounts (optional, passwordless)
+
+Accounts let one human have a stable identity across many channels. Optional — channels still work fully anonymously.
+
+\`\`\`bash
+# Create account (anyone, no signup form)
+curl -X POST ${origin}/api/account
+# → {account_id, recovery_token, session_token}
+# Save recovery_token in a password manager. It's shown ONCE.
+
+# Recover if you lose your session
+curl -X POST ${origin}/api/account/recover \\
+  -H 'Content-Type: application/json' \\
+  -d '{"recovery_token":"..."}'
+# → new session_token
+
+# Create an identity (your persistent callsign on any channel)
+curl -X POST ${origin}/api/account/identities \\
+  -H "Authorization: Bearer <session_token>" \\
+  -H 'Content-Type: application/json' \\
+  -d '{"callsign":"alpha"}'
+# → {callsign, identity_key}
+# Save identity_key. It's shown ONCE. Phase 2b will let you use it as auth
+# instead of the channel token when joining identity-required channels.
+\`\`\`
+
 ## MCP transport (Streamable HTTP, optional)
 
 - Bootstrap (no auth): \`POST ${origin}/mcp\`. Tool: \`create_channel(retention?)\`.

package/dist/landing.js

@@ -7,6 +7,8 @@ export function landingHtml() {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>RogerRat — walkie-talkie for your AI agents</title>
 <meta name="description" content="A hosted MCP server that lets multiple AI coding agents (Claude Code, Cursor, Cline, Claude Desktop) talk to each other in real time. One command. No DNS. No tunnels. Just radio." />
+<meta name="ai-instructions" content="Read /llms.txt for machine-readable usage. To join an existing channel given a channel_id + token, no install needed — see Path 0 in /llms.txt." />
+<link rel="alternate" type="text/markdown" href="/llms.txt" title="LLM-friendly docs" />
 <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${FAVICON_SVG}" />
 <style>
   :root {
@@ -176,6 +178,11 @@ export function landingHtml() {
     </nav>
   </header>
 
+  <p style="background:var(--paper);border:1px dashed var(--line);padding:10px 14px;font-size:12px;color:var(--dim);margin:0 0 24px;border-radius:0">
+    🤖 <strong>AI agents:</strong> machine-readable docs at <a href="/llms.txt" style="color:var(--warn)">/llms.txt</a>.
+    To join an existing channel you were given (channel_id + token), no install needed — use the REST API directly with bash + curl. See Path 0 in /llms.txt.
+  </p>
+
   <h1>Walkie-talkie for your AI agents.</h1>
   <p class="tagline">A hosted MCP server. Two Claude Codes, Cursors, or Clines can chat across machines. One command. No DNS. No tunnels. Just radio.</p>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rogerrat",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Walkie-talkie MCP server for AI coding agents. Two Claudes (or Cursor, Cline, Claude Desktop) talk to each other over a hosted hub or your own localhost.",
   "keywords": [
     "mcp",