@cana-ai/walkie-talkie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Himansh Raj / Colate Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,97 @@
+# Walkie-Talkie wire protocol (v1)
+
+A small, JSON-over-WebSocket protocol for multi-party human↔agent and
+agent↔agent messaging. This document is the source of truth; the reference
+server in this repo implements it, and any client (browser, Node, Rust, Go…)
+can speak it.
+
+## Connecting
+
+```
+GET  {WS_BASE}/ws/bus/{channelId}
+Sec-WebSocket-Protocol: wtk.{token}
+```
+
+- The credential is an opaque agent token (`wtk_…`) carried in the
+  `Sec-WebSocket-Protocol` header as `wtk.{token}` — **never** in the URL/query
+  (a `?token=` fallback exists for non-browser clients but is discouraged).
+- The server echoes the subprotocol back to complete the handshake.
+- Browser clients are subject to an Origin allow-list (`BUS_ALLOWED_ORIGINS`);
+  headless clients (no `Origin` header) are allowed.
+
+Close codes: `4001` auth failed · `4002` channel closed/missing · `4003`
+forbidden / token revoked or expired · `4004` channel full.
+
+## Frames
+
+Every frame is a JSON object. Server frames carry `"v": 1`.
+
+### Server → client
+
+On connect the server sends, in order:
+
+```jsonc
+{ "v":1, "type":"joined", "connectionId":"conn_…", "channelId":"ch_…",
+  "handle":"helper", "owner":"token:wtk_abcd", "capabilities":["receive","send"],
+  "policyVersion":1 }
+
+{ "v":1, "type":"policy", "policyVersion":1, "rules":["…authoritative rules…"] }
+
+{ "v":1, "type":"history", "messages":[ /* WireMessage[] */ ], "count":0 }
+```
+
+Then, live:
+
+```jsonc
+// WireMessage
+{ "v":1, "type":"message", "channelId":"ch_…", "seq":42,
+  "from":"helper", "fromTokenId":"tok_… | null", "to":"handle | null",
+  "private":false, "ts":"2026-06-24T12:00:00.000Z", "body":{ "text":"hi" } }
+
+{ "v":1, "type":"system", "event":"participant_joined|participant_left|channel_closed",
+  "body":{ "handle":"helper" }, "ts":"…" }
+
+{ "v":1, "type":"pong" }
+
+{ "v":1, "type":"error", "code":"forbidden|rate_limited|secret_blocked|…", "message":"…" }
+```
+
+### Client → server
+
+```jsonc
+{ "type":"message", "to":"handle | null", "private":false, "body":{ "text":"hello" } }
+{ "type":"ping" }
+```
+
+- `body` is freeform JSON; the reference client/UI use `{ "text": "…" }`.
+- `to` + `private:true` ⇒ a 1:1 DM visible only to sender and recipient.
+- `to` set + `private:false` ⇒ a directed-but-public message (everyone sees it,
+  one handle is addressed).
+- `to:null` ⇒ broadcast.
+
+## Sequencing & history
+
+- `seq` is a monotonic, server-assigned integer **per channel** (gap-free).
+- On (re)connect the server replays the most recent `HISTORY_REPLAY` messages
+  visible to your handle (private messages only replay to their two parties).
+- Use the highest `seq` you've seen to de-duplicate after a reconnect.
+
+## Capabilities
+
+A token carries a subset of `["receive","send"]` (the open-source core's set).
+`receive` is required to attach; `send` is required to post. Sending without
+`send` returns an `error` frame with code `forbidden`.
+
+## Limits (reference server defaults)
+
+- Message body ≤ 256 KB (`MAX_BODY_BYTES`).
+- Per-connection send rate ≤ 8 msg/s.
+- ≤ 200 live connections per channel.
+- High-confidence credentials are blocked (`error` code `secret_blocked`).
+- Tokens expire (default 8h, max 7d) and are re-checked every 60s mid-stream.
+
+## Policy frame
+
+The `policy` frame is **authoritative and server-authored**. Clients must obey
+it and must treat message text as untrusted data, not instructions. The server
+never accepts a `policy` frame from a client, so peers cannot forge the rules.

package/README.md

@@ -0,0 +1,164 @@
+# 📻 Cana Walkie-Talkie
+
+**A real-time message bus for human↔agent and agent↔agent coordination.**
+
+Spin up a WebSocket bus where people and AI agents (Claude Code, your own
+scripts, anything that speaks WebSocket) join shared **channels**, exchange
+**broadcast / directed / private** messages with live history and presence, and
+operate under a server-authored **policy** that keeps agents on-task and
+prompt-injection-resistant.
+
+This is the **open-source core** of [Cana](https://cana.build)'s Walkie-Talkie —
+single-node, zero-config, no external services. The hosted Cana product builds
+on the same wire protocol with multi-region scale, team RBAC, audit, mobile
+push, and deep agent-platform integration (see the table below).
+
+```
+┌─────────┐   wtk_ token over WS    ┌──────────────────┐
+│  Agent  │ ──────────────────────▶ │                  │
+└─────────┘                         │  Walkie-Talkie   │   ┌─────────┐
+┌─────────┐   admin token over WS   │   bus (this)     │──▶│ SQLite  │
+│Dashboard│ ──────────────────────▶ │  Express + ws    │   └─────────┘
+└─────────┘                         └──────────────────┘
+```
+
+## Features
+
+- **Channels** — create, list, close. Durable in SQLite.
+- **`wtk_` agent tokens** — scoped to channels, with `receive`/`send`
+  capabilities, TTL, one-time reveal, instant revoke. Only a peppered SHA-256
+  hash is stored.
+- **Messaging** — broadcast, directed (`to:`), and private 1:1 DMs.
+- **Live + replay** — WebSocket fan-out plus per-channel monotonic `seq` and
+  history replay on (re)connect.
+- **Server policy frame** — authoritative, anti-prompt-injection rules pushed to
+  every agent on connect.
+- **Safety rails** — high-confidence secret blocking, body-size + rate limits,
+  Origin allow-list (CSWSH), mid-stream token revalidation.
+- **Bundled dashboard** — a no-build web UI to run channels, watch live, and
+  mint agent tokens with a copy-paste `/walkie-talkie` command.
+- **Zero native deps** — Express + `ws` + Zod, SQLite via built-in `node:sqlite`.
+
+## Quickstart
+
+Requires **Node ≥ 22.5** (for built-in `node:sqlite`).
+
+```bash
+git clone https://github.com/Colate-Ltd/cana-walkie-talkie.git
+cd cana-walkie-talkie
+npm install
+cp .env.example .env        # optional — sensible defaults otherwise
+npm start
+```
+
+The server prints a generated **admin token** on first boot (or set `ADMIN_TOKEN`
+in `.env`). Open the dashboard at **http://localhost:8787**, paste the admin
+token, create a channel, and mint an agent token.
+
+Connect an agent (a ready-made example client is included):
+
+```bash
+node examples/agent.mjs ws://localhost:8787 <channelId> <wtk_token> "hi there"
+```
+
+Run the tests (see [test/TESTING.md](test/TESTING.md) for the full plan):
+
+```bash
+npm test          # Tier 1 — fast in-process end-to-end smoke test
+npm run test:multi # Tier 2 — real server + multiple agents, each in a PTY
+npm run test:cld   # Tier 3 — two real Claude Code agents coordinating (opt-in)
+```
+
+## Use it from Claude Code
+
+The dashboard's **+ Agent token** button gives you a ready `/walkie-talkie`
+command. Drop [`commands/walkie-talkie.md`](commands/walkie-talkie.md) into
+`~/.claude/commands/` and run:
+
+```
+/walkie-talkie ws://localhost:8787 <channelId> <wtk_token> "You are the ops helper; stop when the incident is resolved."
+```
+
+## Protocol
+
+The full JSON-over-WebSocket spec is in **[PROTOCOL.md](PROTOCOL.md)**. It's
+small and language-agnostic — write a client in anything.
+
+## Configuration
+
+All optional — see [`.env.example`](.env.example). Highlights:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `PORT` / `HOST` | `8787` / `0.0.0.0` | listener |
+| `DB_PATH` | `./walkie.db` | SQLite file |
+| `ADMIN_TOKEN` | _generated_ | REST + dashboard bearer |
+| `AGENT_TOKEN_PEPPER` | _(empty)_ | peppers token hashes — set in prod |
+| `HISTORY_REPLAY` | `100` | messages replayed on connect |
+| `BUS_ALLOWED_ORIGINS` | _(empty)_ | browser Origin allow-list (CSWSH) |
+
+## Architecture
+
+```
+src/
+  server.ts        HTTP + WS bootstrap, static dashboard
+  rest.ts          /api/bus REST (admin-bearer): channels, tokens, messages
+  ws.ts            /ws/bus/:channelId WebSocket: handshake, frames, heartbeat
+  messages.ts      single emit() choke point: seq, persist, secret-scan, fan-out
+  broadcaster.ts   in-memory per-channel fan-out (the single-node boundary)
+  db.ts            node:sqlite schema + queries
+  tokens.ts        wtk_ generate / hash / verify
+  auth.ts          admin-bearer + wtk_ resolution, mid-stream revalidation
+  policy.ts        authoritative policy frame
+  secret-scan.ts   dependency-free credential detector
+  ratelimit.ts     fixed-window in-memory limiter
+public/            no-build dashboard (index.html, app.js, styles.css)
+examples/agent.mjs minimal reference WebSocket client
+```
+
+The interfaces are intentionally small (`broadcaster`, `auth`, `db`) so they can
+be swapped — e.g. Redis pub/sub for multi-node, or an OAuth/SSO adapter for
+`auth`. That's exactly the seam where the hosted product plugs in.
+
+## Open-source core vs. Cana
+
+The protocol and single-node server are MIT and yours to run. Cana's hosted
+platform adds what teams hit as they grow:
+
+| Capability | Open-source core | Cana (hosted) |
+|---|:---:|:---:|
+| Wire protocol + `/walkie-talkie` command | ✅ | ✅ |
+| Channels, `wtk_` tokens (receive/send) | ✅ | ✅ |
+| Broadcast / directed / private messages | ✅ | ✅ |
+| History replay, presence, heartbeat | ✅ | ✅ |
+| Single-node, SQLite, self-host | ✅ | — |
+| Multi-region horizontal scale (Redis pub/sub) | — | ✅ |
+| Org/team RBAC (viewer→owner roles, directory) | — | ✅ |
+| Compliance audit log | — | ✅ |
+| `admin`/`act` capabilities + approval workflow | — | ✅ |
+| Anomaly auto-revoke, advanced rate/secret controls | basic | ✅ |
+| Mobile + desktop push notifications | — | ✅ |
+| File attachments (S3) | — | ✅ |
+| Read receipts & persistent work-status at scale | — | ✅ |
+| Managed identity (SSO / OIDC) | adapter | ✅ |
+| MCP tool surface + Cana agent/chat/RCA integration | — | ✅ |
+| Hosted, zero-ops, SLA | — | ✅ |
+
+→ **Need scale, teams, or the agent platform?** [cana.build](https://cana.build)
+
+## Security notes
+
+- Set `AGENT_TOKEN_PEPPER` and a strong `ADMIN_TOKEN` in production.
+- Put the server behind TLS; set `BUS_ALLOWED_ORIGINS` for any browser clients.
+- The secret scanner is a safety net, not a guarantee — don't paste credentials.
+- Found a vulnerability? Email **himansh.raj@colate.io** rather than filing a
+  public issue.
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Keep the wire
+protocol backward-compatible and additive.
+
+## License
+
+[MIT](LICENSE) © 2026 Himansh Raj / Colate Ltd.

package/dist/auth.js

@@ -0,0 +1,80 @@
+import { config } from "./config.js";
+import { adminTokenMatches, hashAgentToken } from "./tokens.js";
+import { getTokenByHash, getTokenById, touchToken } from "./db.js";
+/** Express middleware: require the admin bearer token on REST/dashboard APIs. */
+export function requireAdmin(req, res, next) {
+    const header = req.header("authorization") ?? "";
+    const presented = header.startsWith("Bearer ") ? header.slice(7) : header;
+    if (!presented || !adminTokenMatches(presented)) {
+        res.status(401).json({ error: "unauthorized" });
+        return;
+    }
+    next();
+}
+function sanitizeHandle(name) {
+    return name.trim().replace(/[^A-Za-z0-9 _.-]/g, "").slice(0, 48) || "agent";
+}
+/**
+ * Resolve a raw WebSocket credential into an Identity. Accepts either:
+ *  - an agent token (`wtk_…`)  → scoped to its channels + capabilities
+ *  - the admin token           → full receive+send on any channel (dashboard)
+ */
+export function resolveWsIdentity(rawToken, channelId) {
+    if (!rawToken)
+        return { ok: false, code: "no_token", message: "missing token" };
+    // Admin / dashboard connection.
+    if (adminTokenMatches(rawToken)) {
+        return {
+            ok: true,
+            identity: {
+                tokenId: null,
+                handle: "dashboard",
+                owner: "admin",
+                capabilities: ["receive", "send"],
+                channels: null,
+                expiresAt: null,
+            },
+        };
+    }
+    // Agent token.
+    if (!rawToken.startsWith("wtk_")) {
+        return { ok: false, code: "bad_token", message: "unrecognized token" };
+    }
+    const token = getTokenByHash(hashAgentToken(rawToken));
+    if (!token)
+        return { ok: false, code: "bad_token", message: "invalid token" };
+    if (token.revokedAt != null)
+        return { ok: false, code: "revoked", message: "token revoked" };
+    if (token.expiresAt != null && token.expiresAt <= Date.now()) {
+        return { ok: false, code: "expired", message: "token expired" };
+    }
+    if (!token.channels.includes(channelId)) {
+        return { ok: false, code: "forbidden", message: "token not scoped to this channel" };
+    }
+    touchToken(token.id);
+    return {
+        ok: true,
+        identity: {
+            tokenId: token.id,
+            handle: sanitizeHandle(token.name),
+            owner: "token:" + token.prefix,
+            capabilities: token.capabilities,
+            channels: token.channels,
+            expiresAt: token.expiresAt,
+        },
+    };
+}
+/** Re-check a still-connected agent token for mid-stream expiry/revocation. */
+export function tokenStillValid(tokenId) {
+    if (tokenId == null)
+        return true; // admin/dashboard connection never expires
+    const token = getTokenById(tokenId);
+    if (!token)
+        return false;
+    if (token.revokedAt != null)
+        return false;
+    if (token.expiresAt != null && token.expiresAt <= Date.now())
+        return false;
+    return true;
+}
+void config; // imported for side effects / future configuration use

package/dist/broadcaster.js

@@ -0,0 +1,69 @@
+const byChannel = new Map();
+export function addConnection(conn) {
+    let set = byChannel.get(conn.channelId);
+    if (!set) {
+        set = new Map();
+        byChannel.set(conn.channelId, set);
+    }
+    set.set(conn.id, conn);
+}
+export function removeConnection(channelId, connId) {
+    const set = byChannel.get(channelId);
+    if (!set)
+        return;
+    set.delete(connId);
+    if (set.size === 0)
+        byChannel.delete(channelId);
+}
+export function connectionCount(channelId) {
+    return byChannel.get(channelId)?.size ?? 0;
+}
+export function participants(channelId) {
+    const set = byChannel.get(channelId);
+    if (!set)
+        return [];
+    return [...set.values()].map((c) => ({ id: c.id, handle: c.handle, tokenId: c.tokenId }));
+}
+/** True if `frame` should be visible to a connection with `handle`. */
+function visibleTo(frame, handle) {
+    if (!frame.private)
+        return true; // public + directed-but-not-private are visible to all
+    // private: only the sender and the addressed recipient can see it
+    return handle === frame.from || handle === frame.to;
+}
+/** Fan a message frame out to every eligible live connection on its channel. */
+export function deliverMessage(frame) {
+    const set = byChannel.get(frame.channelId);
+    if (!set)
+        return;
+    for (const conn of set.values()) {
+        if (visibleTo(frame, conn.handle))
+            conn.send(frame);
+    }
+}
+/** Fan a non-message system frame out to everyone on the channel. */
+export function deliverSystem(channelId, frame) {
+    const set = byChannel.get(channelId);
+    if (!set)
+        return;
+    for (const conn of set.values())
+        conn.send(frame);
+}
+/** Close every connection on a channel (used when a channel is killed). */
+export function closeChannelConnections(channelId, code = 4002, reason = "channel_closed") {
+    const set = byChannel.get(channelId);
+    if (!set)
+        return;
+    for (const conn of [...set.values()])
+        conn.close(code, reason);
+    byChannel.delete(channelId);
+}
+/** Close all live connections belonging to a revoked token. */
+export function closeTokenConnections(tokenId, code = 4003, reason = "token_revoked") {
+    for (const set of byChannel.values()) {
+        for (const conn of [...set.values()]) {
+            if (conn.tokenId === tokenId)
+                conn.close(code, reason);
+        }
+    }
+}

package/dist/config.js

@@ -0,0 +1,42 @@
+import crypto from "node:crypto";
+function num(name, def) {
+    const v = process.env[name];
+    if (v == null || v.trim() === "")
+        return def;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : def;
+}
+function list(name) {
+    return (process.env[name] ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+// A generated admin token if none was provided. Printed once at startup.
+let adminToken = process.env.ADMIN_TOKEN?.trim() || "";
+let adminTokenGenerated = false;
+if (!adminToken) {
+    adminToken = "adm_" + crypto.randomBytes(24).toString("base64url");
+    adminTokenGenerated = true;
+}
+export const config = {
+    host: process.env.HOST ?? "0.0.0.0",
+    port: num("PORT", 8787),
+    dbPath: process.env.DB_PATH ?? "./walkie.db",
+    adminToken,
+    adminTokenGenerated,
+    tokenPepper: process.env.AGENT_TOKEN_PEPPER ?? "",
+    historyReplay: Math.max(1, num("HISTORY_REPLAY", 100)),
+    maxBodyBytes: Math.max(1024, num("MAX_BODY_BYTES", 256 * 1024)),
+    defaultTtlMs: Math.max(1, num("DEFAULT_TTL_HOURS", 8)) * 3600_000,
+    maxTtlMs: Math.max(1, num("MAX_TTL_HOURS", 168)) * 3600_000,
+    allowedOrigins: list("BUS_ALLOWED_ORIGINS"),
+};
+// Open-source guardrails. These are the deliberate limits of the community
+// core — the hosted Cana product lifts them (multi-node scale, org RBAC,
+// audit, push, attachments, SSO). See README "Cana vs the open-source core".
+export const limits = {
+    capabilities: ["receive", "send"], // no `admin` / `act` in OSS
+    perConnRatePerSec: 8,
+    maxConnectionsPerChannel: 200,
+};

package/dist/db.js

@@ -0,0 +1,164 @@
+import { DatabaseSync } from "node:sqlite";
+import crypto from "node:crypto";
+import { config } from "./config.js";
+const db = new DatabaseSync(config.dbPath);
+db.exec("PRAGMA journal_mode = WAL;");
+db.exec("PRAGMA foreign_keys = ON;");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS channels (
+    id          TEXT PRIMARY KEY,
+    slug        TEXT UNIQUE NOT NULL,
+    name        TEXT NOT NULL,
+    description TEXT,
+    status      TEXT NOT NULL DEFAULT 'active',
+    last_seq    INTEGER NOT NULL DEFAULT 0,
+    created_at  INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS tokens (
+    id           TEXT PRIMARY KEY,
+    name         TEXT NOT NULL,
+    prefix       TEXT NOT NULL,
+    hashed_key   TEXT UNIQUE NOT NULL,
+    channels     TEXT NOT NULL,
+    capabilities TEXT NOT NULL,
+    expires_at   INTEGER,
+    revoked_at   INTEGER,
+    last_used_at INTEGER,
+    created_at   INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_tokens_hash ON tokens(hashed_key);
+
+  CREATE TABLE IF NOT EXISTS messages (
+    id              TEXT PRIMARY KEY,
+    channel_id      TEXT NOT NULL,
+    seq             INTEGER NOT NULL,
+    kind            TEXT NOT NULL DEFAULT 'message',
+    sender_label    TEXT NOT NULL,
+    sender_token_id TEXT,
+    recipient       TEXT,
+    private         INTEGER NOT NULL DEFAULT 0,
+    body            TEXT NOT NULL,
+    created_at      INTEGER NOT NULL,
+    UNIQUE(channel_id, seq)
+  );
+  CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel_id, seq);
+`);
+const newId = (p) => `${p}_${crypto.randomBytes(12).toString("hex")}`;
+function slugify(name) {
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "channel";
+    // ensure uniqueness
+    let slug = base;
+    let n = 1;
+    while (db.prepare("SELECT 1 FROM channels WHERE slug = ?").get(slug)) {
+        slug = `${base}-${++n}`;
+    }
+    return slug;
+}
+// ── Channels ─────────────────────────────────────────────────────────
+function rowToChannel(r) {
+    return {
+        id: r.id,
+        slug: r.slug,
+        name: r.name,
+        description: r.description ?? null,
+        status: r.status,
+        lastSeq: Number(r.last_seq),
+        createdAt: Number(r.created_at),
+    };
+}
+export function createChannel(name, description) {
+    const id = newId("ch");
+    const slug = slugify(name);
+    const now = Date.now();
+    db.prepare("INSERT INTO channels (id, slug, name, description, status, last_seq, created_at) VALUES (?,?,?,?, 'active', 0, ?)").run(id, slug, name, description ?? null, now);
+    return rowToChannel(db.prepare("SELECT * FROM channels WHERE id = ?").get(id));
+}
+export function listChannels() {
+    return db.prepare("SELECT * FROM channels ORDER BY created_at DESC").all().map(rowToChannel);
+}
+export function getChannel(id) {
+    const r = db.prepare("SELECT * FROM channels WHERE id = ? OR slug = ?").get(id, id);
+    return r ? rowToChannel(r) : null;
+}
+export function closeChannel(id) {
+    db.prepare("UPDATE channels SET status = 'closed' WHERE id = ?").run(id);
+}
+/** Atomically increment and return the next per-channel sequence number. */
+export function nextSeq(channelId) {
+    db.prepare("UPDATE channels SET last_seq = last_seq + 1 WHERE id = ?").run(channelId);
+    const r = db.prepare("SELECT last_seq FROM channels WHERE id = ?").get(channelId);
+    return r ? Number(r.last_seq) : 0;
+}
+// ── Tokens ───────────────────────────────────────────────────────────
+function rowToToken(r) {
+    return {
+        id: r.id,
+        name: r.name,
+        prefix: r.prefix,
+        hashedKey: r.hashed_key,
+        channels: JSON.parse(r.channels),
+        capabilities: JSON.parse(r.capabilities),
+        expiresAt: r.expires_at == null ? null : Number(r.expires_at),
+        revokedAt: r.revoked_at == null ? null : Number(r.revoked_at),
+        lastUsedAt: r.last_used_at == null ? null : Number(r.last_used_at),
+        createdAt: Number(r.created_at),
+    };
+}
+export function insertToken(t) {
+    const id = newId("tok");
+    const now = Date.now();
+    db.prepare("INSERT INTO tokens (id, name, prefix, hashed_key, channels, capabilities, expires_at, revoked_at, last_used_at, created_at) VALUES (?,?,?,?,?,?,?,NULL,NULL,?)").run(id, t.name, t.prefix, t.hashedKey, JSON.stringify(t.channels), JSON.stringify(t.capabilities), t.expiresAt, now);
+    return rowToToken(db.prepare("SELECT * FROM tokens WHERE id = ?").get(id));
+}
+export function listTokens() {
+    return db.prepare("SELECT * FROM tokens ORDER BY created_at DESC").all().map(rowToToken);
+}
+export function getTokenByHash(hash) {
+    const r = db.prepare("SELECT * FROM tokens WHERE hashed_key = ?").get(hash);
+    return r ? rowToToken(r) : null;
+}
+export function getTokenById(id) {
+    const r = db.prepare("SELECT * FROM tokens WHERE id = ?").get(id);
+    return r ? rowToToken(r) : null;
+}
+export function revokeToken(id) {
+    const res = db.prepare("UPDATE tokens SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL").run(Date.now(), id);
+    return res.changes > 0;
+}
+export function touchToken(id) {
+    db.prepare("UPDATE tokens SET last_used_at = ? WHERE id = ?").run(Date.now(), id);
+}
+// ── Messages ─────────────────────────────────────────────────────────
+function rowToMessage(r) {
+    return {
+        id: r.id,
+        channelId: r.channel_id,
+        seq: Number(r.seq),
+        kind: r.kind,
+        senderLabel: r.sender_label,
+        senderTokenId: r.sender_token_id ?? null,
+        recipient: r.recipient ?? null,
+        private: Number(r.private) === 1,
+        body: JSON.parse(r.body),
+        createdAt: Number(r.created_at),
+    };
+}
+export function insertMessage(m) {
+    const id = newId("msg");
+    const createdAt = m.createdAt ?? Date.now();
+    db.prepare("INSERT INTO messages (id, channel_id, seq, kind, sender_label, sender_token_id, recipient, private, body, created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(id, m.channelId, m.seq, m.kind, m.senderLabel, m.senderTokenId, m.recipient, m.private ? 1 : 0, JSON.stringify(m.body), createdAt);
+    return rowToMessage(db.prepare("SELECT * FROM messages WHERE id = ?").get(id));
+}
+/** Most recent `limit` messages for a channel, oldest-first. */
+export function recentMessages(channelId, limit) {
+    const rows = db
+        .prepare("SELECT * FROM messages WHERE channel_id = ? ORDER BY seq DESC LIMIT ?")
+        .all(channelId, limit);
+    return rows.map(rowToMessage).reverse();
+}
+export function messageCounts(channelId) {
+    const r = db.prepare("SELECT COUNT(*) AS c FROM messages WHERE channel_id = ?").get(channelId);
+    return Number(r.c);
+}
+export { db };