@abraca/dabra 1.9.1 → 2.0.0

package/src/EncryptedChatClient.ts

@@ -0,0 +1,173 @@
+/**
+ * EncryptedChatClient — `ChatClient` wrapper that transparently encrypts
+ * message content for channels in `e2e` mode and decrypts entries read
+ * back from the period doc's `messages` Y.Array.
+ *
+ * Threat model
+ *   - Server cannot read message bodies (the `content` field is opaque
+ *     ciphertext bytes, base64-encoded into the wire string).
+ *   - Server CAN see `sender_id`, `channel_doc_id`, `period_id`, `ts`,
+ *     `mentions[]` (kept cleartext for fan-out), `message_id`,
+ *     and the `server_sig` it stamps. That envelope is the only thing
+ *     the server inspects to do its job.
+ *
+ * Wire format
+ *   `content` for an e2e message is the literal string
+ *     `"e2e:1:<base64>"`
+ *   where the decoded blob is `[nonce(12) || AES-GCM-ciphertext]` and
+ *   the AES-256-GCM key is the channel's existing DocKey (the same one
+ *   used for `EncryptedY` doc-level encryption — same threat boundary,
+ *   no extra key derivation, identical envelope distribution).
+ *
+ * The `e2e:1:` sentinel is a strict prefix to disambiguate from
+ *   cleartext content that happens to start with "{". Never unwrap a
+ *   message whose content doesn't start with the sentinel — passing
+ *   ciphertext from a server you don't trust through `decrypt` would
+ *   open the door to malformed-input oracles.
+ */
+
+import { encryptField, decryptField } from "./EncryptedY.ts";
+import { DocKeyManager } from "./DocKeyManager.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import type { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";
+import type {
+  ChatClient,
+  SendMessageInput,
+  SendMessageResult,
+  EditMessageInput,
+} from "./ChatClient.ts";
+
+const SENTINEL = "e2e:1:";
+
+function toBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!);
+  return btoa(s);
+}
+
+function fromBase64(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Returns true if `content` is wrapped by this module (i.e. an `e2e:1:`
+ * envelope). Cleartext content always returns false.
+ */
+export function isEncryptedContent(content: string): boolean {
+  return typeof content === "string" && content.startsWith(SENTINEL);
+}
+
+/**
+ * Decrypt an `e2e:1:` envelope back to cleartext using the channel's
+ * DocKey. Returns null if the envelope is malformed (don't surface
+ * partial decryption — show the user a placeholder instead).
+ */
+export async function decryptChatContent(content: string, docKey: CryptoKey): Promise<string | null> {
+  if (!isEncryptedContent(content)) return content; // already cleartext
+  try {
+    const blob = fromBase64(content.slice(SENTINEL.length));
+    const plain = await decryptField(blob, docKey);
+    return new TextDecoder().decode(plain);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Encrypt cleartext into an `e2e:1:` envelope ready to send as the
+ * stateless `messages:send` `content` field.
+ */
+export async function encryptChatContent(content: string, docKey: CryptoKey): Promise<string> {
+  const blob = await encryptField(new TextEncoder().encode(content), docKey);
+  return SENTINEL + toBase64(blob);
+}
+
+/**
+ * Per-channel encryption-mode + DocKey resolver. Caches the encryption
+ * mode lookup for `cacheTtlMs`; the DocKey itself is cached inside
+ * `DocKeyManager`. Returns `null` for non-E2E channels.
+ */
+export class ChannelKeyResolver {
+  private modeCache = new Map<string, { mode: "none" | "cse" | "e2e"; fetchedAt: number }>();
+  private static readonly DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+  constructor(
+    private readonly client: AbracadabraClient,
+    private readonly docKeys: DocKeyManager,
+    private readonly keystore: CryptoIdentityKeystore,
+    private readonly options: { cacheTtlMs?: number } = {},
+  ) {}
+
+  async modeFor(channelDocId: string): Promise<"none" | "cse" | "e2e"> {
+    const cached = this.modeCache.get(channelDocId);
+    const ttl = this.options.cacheTtlMs ?? ChannelKeyResolver.DEFAULT_TTL_MS;
+    if (cached && Date.now() - cached.fetchedAt < ttl) return cached.mode;
+    const info = await this.client.getDocEncryption(channelDocId);
+    const mode = info.effective_mode;
+    this.modeCache.set(channelDocId, { mode, fetchedAt: Date.now() });
+    return mode;
+  }
+
+  /**
+   * Returns the DocKey for an E2E channel, or null for cleartext channels
+   * (no envelope to fetch). Throws if the channel is E2E but no envelope
+   * exists for the current user — the caller should let the send fail
+   * loudly rather than fall back to cleartext, which would silently
+   * downgrade the threat model.
+   */
+  async docKeyFor(channelDocId: string): Promise<CryptoKey | null> {
+    const mode = await this.modeFor(channelDocId);
+    if (mode !== "e2e") return null;
+    const key = await this.docKeys.getDocKey(channelDocId, this.client, this.keystore);
+    if (!key) {
+      throw new Error(
+        `EncryptedChatClient: no key envelope for channel ${channelDocId} — user is not provisioned for this E2E channel.`,
+      );
+    }
+    return key;
+  }
+
+  /** Drop the cached encryption mode for `channelDocId` (or all). */
+  clearCache(channelDocId?: string): void {
+    if (channelDocId) this.modeCache.delete(channelDocId);
+    else this.modeCache.clear();
+  }
+}
+
+/**
+ * Drop-in wrapper around an existing ChatClient that intercepts the
+ * write side (`send` / `edit`) and encrypts content for E2E channels.
+ * Reading is handled separately — the consumer pumps the period's Y.Array
+ * directly and calls `decryptChatContent` per record.
+ *
+ * Channels in `none` or `cse` mode are passed through untouched.
+ */
+export class EncryptedChatClient {
+  constructor(
+    private readonly inner: ChatClient,
+    private readonly resolver: ChannelKeyResolver,
+  ) {}
+
+  async send(input: SendMessageInput): Promise<SendMessageResult> {
+    const docKey = await this.resolver.docKeyFor(input.channel_doc_id);
+    if (!docKey) return this.inner.send(input);
+    const ciphertext = await encryptChatContent(input.content, docKey);
+    return this.inner.send({ ...input, content: ciphertext });
+  }
+
+  async edit(input: EditMessageInput): Promise<void> {
+    const docKey = await this.resolver.docKeyFor(input.channel_doc_id);
+    if (!docKey) return this.inner.edit(input);
+    const ciphertext = await encryptChatContent(input.content, docKey);
+    return this.inner.edit({ ...input, content: ciphertext });
+  }
+
+  // Pass-through methods that don't carry encryptable content.
+  delete(...args: Parameters<ChatClient["delete"]>) { return this.inner.delete(...args); }
+  markRead(...args: Parameters<ChatClient["markRead"]>) { return this.inner.markRead(...args); }
+  typing(...args: Parameters<ChatClient["typing"]>) { return this.inner.typing(...args); }
+  destroy() { this.inner.destroy(); }
+}

package/src/EncryptedY.ts

@@ -16,7 +16,7 @@ import * as Y from "yjs";
 export async function encryptField(value: Uint8Array, docKey: CryptoKey): Promise<Uint8Array> {
 	const nonce = crypto.getRandomValues(new Uint8Array(12));
 	const ciphertext = new Uint8Array(
-		await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, docKey, value),
+		await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce as BufferSource }, docKey, value as BufferSource),
 	);
 	const result = new Uint8Array(12 + ciphertext.length);
 	result.set(nonce, 0);
@@ -28,7 +28,7 @@ export async function encryptField(value: Uint8Array, docKey: CryptoKey): Promis
 export async function decryptField(ciphertext: Uint8Array, docKey: CryptoKey): Promise<Uint8Array> {
 	const nonce = ciphertext.slice(0, 12);
 	const ct = ciphertext.slice(12);
-	return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce }, docKey, ct));
+	return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce as BufferSource }, docKey, ct as BufferSource));
 }
 
 // ── EncryptedYMap ─────────────────────────────────────────────────────────────

package/src/IdentityDoc.ts

@@ -33,6 +33,31 @@ export function deriveIdentityDocId(publicKeyB64: string): string {
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+/**
+ * Derives a deterministic UUID for the DM doc between two participants
+ * (independent of which side computes it). The two pubkeys are sorted
+ * lexicographically before hashing so both clients produce the same id —
+ * this lets `findOrCreateDmDoc` race-tolerantly create-or-claim the doc
+ * without coordinating; whichever client wins the create-with-id call
+ * is fine, the other gets a Conflict and reuses the existing id.
+ *
+ * @param pubkeyA Base64url-encoded Ed25519 public key (32 bytes).
+ * @param pubkeyB Base64url-encoded Ed25519 public key (32 bytes).
+ */
+export function deriveDmDocId(pubkeyA: string, pubkeyB: string): string {
+	const [first, second] = [pubkeyA, pubkeyB].sort();
+	const hash = sha256(
+		new TextEncoder().encode(`abracadabra:dm:${first}:${second}`),
+	);
+	const bytes = new Uint8Array(hash.buffer, hash.byteOffset, 16);
+	bytes[6] = (bytes[6] & 0x0f) | 0x50;
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+		"",
+	);
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface IdentityProfile {

package/src/MnemonicKeyDerivation.ts

@@ -142,8 +142,8 @@ export async function wrapSeed(
 	wrappingKeyBytes: Uint8Array,
 ): Promise<{ ciphertext: ArrayBuffer; iv: Uint8Array }> {
 	const iv = crypto.getRandomValues(new Uint8Array(12));
-	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes, "AES-GCM", false, ["encrypt"]);
-	const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, seed);
+	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes as BufferSource, "AES-GCM", false, ["encrypt"]);
+	const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv as BufferSource }, key, seed as BufferSource);
 	return { ciphertext, iv };
 }
 
@@ -161,7 +161,7 @@ export async function unwrapSeed(
 	iv: Uint8Array,
 	wrappingKeyBytes: Uint8Array,
 ): Promise<Uint8Array> {
-	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes, "AES-GCM", false, ["decrypt"]);
-	const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);
+	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes as BufferSource, "AES-GCM", false, ["decrypt"]);
+	const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: iv as BufferSource }, key, ciphertext);
 	return new Uint8Array(plaintext);
 }

package/src/NotificationsClient.ts

@@ -1,10 +1,4 @@
 import EventEmitter from "./EventEmitter.ts";
-import type {
-  CreateNotificationInput,
-  FetchNotificationsInput,
-  NotificationReadUpdate,
-  NotificationRecord,
-} from "./types.ts";
 import type { ChatClientTransport } from "./ChatClient.ts";
 
 type PendingResolver<T> = {
@@ -15,29 +9,79 @@ type PendingResolver<T> = {
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+/** Per-user inbox doc entry. Mirrors `InboxEntry` on the server. */
+export interface InboxEntry {
+  id: string;
+  /** "mention" | "reply" | "dm" | "system". */
+  kind: string;
+  channel_doc_id: string;
+  message_id?: string | null;
+  sender_id?: string | null;
+  sender_name?: string | null;
+  /** Empty for E2E channels (server can't read body). Filled otherwise. */
+  preview?: string | null;
+  ts: number;
+  /** Synthesized client-side from the inbox doc's `read` Y.Map. */
+  read: boolean;
+}
+
+export interface FetchInboxInput {
+  before?: number;
+  limit?: number;
+  unread_only?: boolean;
+}
+
+export interface MarkReadInput {
+  id?: string;
+  ids?: string[];
+  source_id?: string;
+  all?: boolean;
+}
+
 /**
- * Typed client for the Abracadabra notifications feature.
+ * Thin façade over the `messages:inbox_*` stateless protocol.
  *
- * Emits:
- *   - `new`        → NotificationRecord      (incoming notify:new broadcast)
- *   - `readUpdate` → NotificationReadUpdate  (broadcast after mark_read / mark_all_read)
+ * Per-user notifications live as Y.Array entries on the user's inbox doc
+ * (`kind = "inbox"`, owned by the user, child of the server root, server-only
+ * writer). Real-time observation of new entries is a Y.Array observer the
+ * consumer attaches via `AbracadabraProvider` on the inbox doc.
+ *
+ * This client handles only the request/response layer:
+ *   - `fetch()` issues `messages:inbox_fetch`, returns the entry list.
+ *   - `markRead()` issues `messages:inbox_mark_read` (id / ids / source_id /
+ *     all variants).
+ *
+ * For incoming notification observation, open an AbracadabraProvider on the
+ * inbox doc and observe its `entries` Y.Array directly. The dashboard's
+ * `useNotifications` composable does this.
  */
 export class NotificationsClient extends EventEmitter {
   private readonly provider: ChatClientTransport;
   private readonly responseTimeoutMs: number;
   private readonly pending: Map<string, PendingResolver<any>[]> = new Map();
   private readonly boundOnStateless: (data: { payload: string }) => void;
+  private readonly boundOnServerError: (data: {
+    source: string;
+    code: string;
+    message: string;
+    meta?: unknown;
+  }) => void;
 
   constructor(provider: ChatClientTransport, options?: { responseTimeoutMs?: number }) {
     super();
     this.provider = provider;
     this.responseTimeoutMs = options?.responseTimeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.boundOnStateless = (data) => this.handleStateless(data.payload);
+    this.boundOnServerError = (data) => this.handleServerError(data);
     this.provider.on("stateless", this.boundOnStateless);
+    // BaseProvider emits `serverError` for `{type:"error",source,code}` frames
+    // instead of `stateless`. Subscribe so inbox request rejections surface.
+    this.provider.on("serverError", this.boundOnServerError);
   }
 
   destroy(): void {
     this.provider.off("stateless", this.boundOnStateless);
+    this.provider.off("serverError", this.boundOnServerError);
     for (const queue of this.pending.values()) {
       for (const p of queue) {
         clearTimeout(p.timer);
@@ -48,34 +92,12 @@ export class NotificationsClient extends EventEmitter {
     this.removeAllListeners();
   }
 
-  // ── Outgoing requests ──────────────────────────────────────────────────────
-
-  /**
-   * Create a notification targeting a specific recipient. Requires elevated role
-   * (service or admin); a `server:error` event with code `forbidden` is emitted
-   * by the underlying provider if the caller lacks permission.
-   */
-  create(input: CreateNotificationInput): void {
-    this.provider.sendStateless(
-      JSON.stringify({
-        type: "notify:create",
-        recipient_id: input.recipient_id,
-        ...(input.notification_type !== undefined ? { notification_type: input.notification_type } : {}),
-        title: input.title,
-        ...(input.body !== undefined ? { body: input.body } : {}),
-        ...(input.icon !== undefined ? { icon: input.icon } : {}),
-        ...(input.link !== undefined ? { link: input.link } : {}),
-        ...(input.source_id !== undefined ? { source_id: input.source_id } : {}),
-      }),
-    );
-  }
-
-  /** Fetch notification history for the current user. */
-  fetch(input: FetchNotificationsInput = {}): Promise<{ notifications: NotificationRecord[] }> {
-    const promise = this.enqueue<{ notifications: NotificationRecord[] }>("notify:history");
+  /** Fetch a slice of the calling user's inbox. Resolves with the entries. */
+  fetch(input: FetchInboxInput = {}): Promise<{ entries: InboxEntry[] }> {
+    const promise = this.enqueue<{ entries: InboxEntry[] }>("messages:inbox_history");
     this.provider.sendStateless(
       JSON.stringify({
-        type: "notify:fetch",
+        type: "messages:inbox_fetch",
         ...(input.before !== undefined ? { before: input.before } : {}),
         ...(input.limit !== undefined ? { limit: input.limit } : {}),
         ...(input.unread_only !== undefined ? { unread_only: input.unread_only } : {}),
@@ -84,69 +106,66 @@ export class NotificationsClient extends EventEmitter {
     return promise;
   }
 
-  /** Mark a single notification, or a batch, as read. */
-  markRead(target: { id: string } | { ids: string[] }): void {
-    const body: Record<string, unknown> = { type: "notify:mark_read" };
-    if ("id" in target) body.id = target.id;
-    else body.ids = target.ids;
+  /**
+   * Mark inbox entries read. One of `id`, `ids`, `source_id`, or `all`.
+   * Returns when the server has acked.
+   */
+  markRead(input: MarkReadInput): Promise<void> {
+    const body: Record<string, unknown> = { type: "messages:inbox_mark_read" };
+    if (input.all === true) body.all = true;
+    else if (input.source_id !== undefined) body.source_id = input.source_id;
+    else if (input.ids !== undefined) body.ids = input.ids;
+    else if (input.id !== undefined) body.id = input.id;
+    else return Promise.reject(new Error("markRead: one of id/ids/source_id/all required"));
+
+    const promise = this.enqueue<void>("messages:inbox_mark_read");
     this.provider.sendStateless(JSON.stringify(body));
-  }
-
-  /** Mark every notification for the current user as read. */
-  markAllRead(): void {
-    this.provider.sendStateless(JSON.stringify({ type: "notify:mark_all_read" }));
-  }
-
-  /** Mark all notifications generated by the given source (e.g. a chat channel) as read. */
-  markReadBySource(sourceId: string): void {
-    this.provider.sendStateless(
-      JSON.stringify({ type: "notify:mark_read_by_source", source_id: sourceId }),
-    );
-  }
-
-  // ── Event helpers ─────────────────────────────────────────────────────────
-
-  onNew(fn: (n: NotificationRecord) => void): this {
-    return this.on("new", fn) as this;
-  }
-
-  onReadUpdate(fn: (u: NotificationReadUpdate) => void): this {
-    return this.on("readUpdate", fn) as this;
+    return promise;
   }
 
   // ── Internals ─────────────────────────────────────────────────────────────
 
-  private enqueue<T>(type: string): Promise<T> {
+  private enqueue<T>(source: string): Promise<T> {
     return new Promise<T>((resolve, reject) => {
       const timer = setTimeout(() => {
-        this.removePending(type, entry);
-        reject(new Error(`NotificationsClient: timeout waiting for ${type} response`));
+        this.removePending(source, entry);
+        reject(new Error(`NotificationsClient: timeout waiting for ${source}`));
       }, this.responseTimeoutMs);
       const entry: PendingResolver<T> = { resolve, reject, timer };
-      const queue = this.pending.get(type) ?? [];
+      const queue = this.pending.get(source) ?? [];
       queue.push(entry);
-      this.pending.set(type, queue);
+      this.pending.set(source, queue);
     });
   }
 
-  private removePending(type: string, entry: PendingResolver<any>): void {
-    const queue = this.pending.get(type);
+  private removePending(source: string, entry: PendingResolver<any>): void {
+    const queue = this.pending.get(source);
     if (!queue) return;
     const idx = queue.indexOf(entry);
     if (idx >= 0) queue.splice(idx, 1);
-    if (queue.length === 0) this.pending.delete(type);
+    if (queue.length === 0) this.pending.delete(source);
   }
 
-  private resolveNext<T>(type: string, value: T): boolean {
-    const queue = this.pending.get(type);
+  private resolveNext<T>(source: string, value: T): boolean {
+    const queue = this.pending.get(source);
     if (!queue || queue.length === 0) return false;
     const next = queue.shift()!;
-    if (queue.length === 0) this.pending.delete(type);
+    if (queue.length === 0) this.pending.delete(source);
     clearTimeout(next.timer);
     next.resolve(value);
     return true;
   }
 
+  private rejectNext(source: string, err: Error): boolean {
+    const queue = this.pending.get(source);
+    if (!queue || queue.length === 0) return false;
+    const next = queue.shift()!;
+    if (queue.length === 0) this.pending.delete(source);
+    clearTimeout(next.timer);
+    next.reject(err);
+    return true;
+  }
+
   private handleStateless(payload: string): void {
     let parsed: any;
     try {
@@ -155,31 +174,34 @@ export class NotificationsClient extends EventEmitter {
       return;
     }
     const type: unknown = parsed?.type;
-    if (typeof type !== "string" || !type.startsWith("notify:")) return;
+    if (typeof type !== "string") return;
 
-    switch (type) {
-      case "notify:new": {
-        const { type: _t, ...rest } = parsed;
-        this.emit("new", rest as NotificationRecord);
-        break;
-      }
-      case "notify:history": {
-        this.resolveNext("notify:history", {
-          notifications: parsed.notifications ?? [],
-        });
-        break;
-      }
-      case "notify:read_update": {
-        const update: NotificationReadUpdate = {
-          recipient_id: parsed.recipient_id,
-        };
-        if (parsed.ids !== undefined) update.ids = parsed.ids;
-        if (parsed.all !== undefined) update.all = parsed.all;
-        this.emit("readUpdate", update);
-        break;
-      }
-      default:
-        break;
+    if (type === "messages:inbox_history") {
+      this.resolveNext("messages:inbox_history", {
+        entries: parsed.entries ?? [],
+      });
+      return;
+    }
+    if (type === "messages:ok" && parsed.source === "messages:inbox_mark_read") {
+      this.resolveNext("messages:inbox_mark_read", undefined);
+      return;
+    }
+  }
+
+  private handleServerError(data: {
+    source: string;
+    code: string;
+    message: string;
+    meta?: unknown;
+  }): void {
+    if (data.source !== "messages:inbox_fetch" && data.source !== "messages:inbox_mark_read") {
+      return;
     }
+    const key =
+      data.source === "messages:inbox_fetch" ? "messages:inbox_history" : data.source;
+    this.rejectNext(
+      key,
+      new Error(`${data.code ?? "error"}: ${data.message ?? "inbox request failed"}`),
+    );
   }
 }

package/src/OutgoingMessages/SubdocMessage.ts

@@ -1,5 +1,5 @@
 import { writeVarString, writeVarUint } from "lib0/encoding";
-import type { OutgoingMessageArguments } from "../types.ts";
+import type { AbracadabraOutgoingMessageArguments } from "../types.ts";
 import { MessageType } from "../types.ts";
 import { OutgoingMessage } from "../OutgoingMessage.ts";
 
@@ -18,7 +18,7 @@ export class SubdocMessage extends OutgoingMessage {
 
 	description = "SubdocRegistration";
 
-	get(args: Partial<OutgoingMessageArguments>) {
+	get(args: Partial<AbracadabraOutgoingMessageArguments>) {
 		if (!args.documentName) {
 			throw new Error("SubdocMessage requires `documentName` (parent id).");
 		}