@agora-sdk/secure-chat-core 0.6.5 → 0.8.0

package/dist/cjs/content/mimi-content.d.ts

@@ -0,0 +1,194 @@
+import { type CborMap } from "./cbor.js";
+/**
+ * Part cardinality tag. Values per draft-ietf-mimi-content-08
+ * (`nullpart=0, single=1, external=2, multi=3`).
+ */
+export declare const Cardinality: {
+    readonly Null: 0;
+    readonly Single: 1;
+    readonly External: 2;
+    readonly Multi: 3;
+};
+/** The set of valid {@link Cardinality} tag values. */
+export type Cardinality = (typeof Cardinality)[keyof typeof Cardinality];
+/**
+ * Part disposition (draft-ietf-mimi-content-08 `baseDispos`). `Reaction` distinguishes a reaction
+ * from a reply; `Attachment`/`Inline`/etc. drive client rendering.
+ */
+export declare const Disposition: {
+    readonly Unspecified: 0;
+    readonly Render: 1;
+    readonly Reaction: 2;
+    readonly Profile: 3;
+    readonly Inline: 4;
+    readonly Icon: 5;
+    readonly Attachment: 6;
+    readonly Session: 7;
+    readonly Preview: 8;
+};
+/** The set of valid {@link Disposition} values. */
+export type Disposition = (typeof Disposition)[keyof typeof Disposition];
+/**
+ * {@link MultiPart} `partSemantics` — how a client treats the child parts (draft-ietf-mimi-content-08:
+ * `chooseOne=0, singleUnit=1, processAll=2`).
+ */
+export declare const PartSemantics: {
+    readonly ChooseOne: 0;
+    readonly SingleUnit: 1;
+    readonly ProcessAll: 2;
+};
+/** The set of valid {@link PartSemantics} values. */
+export type PartSemantics = (typeof PartSemantics)[keyof typeof PartSemantics];
+/**
+ * Named-Information hash algorithm. SHA-256 is the only value we emit (identifier `0x01`, per
+ * draft-ietf-mimi-content-08).
+ */
+export declare const HashAlg: {
+    readonly Sha256: 1;
+};
+/** The set of valid {@link HashAlg} values. */
+export type HashAlg = (typeof HashAlg)[keyof typeof HashAlg];
+/** A tombstone body (delete / un-react) — `NullPart` with the NestedPart wrapper's disposition/language. */
+export interface NullPart {
+    /** Cardinality tag — always {@link Cardinality.Null}. */
+    cardinality: typeof Cardinality.Null;
+    /** Wrapper disposition (typically {@link Disposition.Render}); kept for wire-faithful round-trip. */
+    disposition: Disposition;
+    /** BCP-47 language tag, or `""`. */
+    language: string;
+}
+/** An inline body part (text, reaction token, …) — draft `SinglePart` + the NestedPart wrapper fields. */
+export interface SinglePart {
+    /** Cardinality tag — always {@link Cardinality.Single}. */
+    cardinality: typeof Cardinality.Single;
+    /** How a client should treat this part (`Render` for text, `Reaction` for a reaction token, …). */
+    disposition: Disposition;
+    /** BCP-47 language tag for `content`, or `""` when not applicable. */
+    language: string;
+    /** MIME type of `content` (e.g. `text/markdown`). */
+    contentType: string;
+    /** The raw body bytes (UTF-8 for text types). */
+    content: Uint8Array;
+}
+/** An external (by-reference, encrypted) attachment part — Tier 3; encoded, not yet surfaced. */
+export interface ExternalPart {
+    /** Cardinality tag — always {@link Cardinality.External}. */
+    cardinality: typeof Cardinality.External;
+    /** How a client should treat this part (typically {@link Disposition.Attachment}). */
+    disposition: Disposition;
+    /** BCP-47 language tag, or `""`. */
+    language: string;
+    /** MIME type of the referenced blob. */
+    contentType: string;
+    /** Fetch URL for the encrypted blob. */
+    url: string;
+    /** Absolute expiry of the URL (0 = none). */
+    expires: number;
+    /** Plaintext size in bytes. */
+    size: number;
+    /** Symmetric encryption algorithm identifier for the blob (draft `encAlg`). */
+    encAlgorithm: number;
+    /** Symmetric key for the blob (kept client-side only). */
+    key: Uint8Array;
+    /** AEAD nonce. */
+    nonce: Uint8Array;
+    /** AEAD associated data. */
+    aad: Uint8Array;
+    /** Hash algorithm of {@link ExternalPart.contentHash} (we emit {@link HashAlg.Sha256}). */
+    hashAlgorithm: HashAlg;
+    /** Hash of the plaintext blob (integrity). */
+    contentHash: Uint8Array;
+    /** Human-readable description / alt text. */
+    description: string;
+    /** Suggested filename. */
+    filename: string;
+}
+/** A composite body of ordered sub-parts (draft `MultiPart`; at least 2 children). */
+export interface MultiPart {
+    /** Cardinality tag — always {@link Cardinality.Multi}. */
+    cardinality: typeof Cardinality.Multi;
+    /** Wrapper disposition for the composite. */
+    disposition: Disposition;
+    /** BCP-47 language tag, or `""`. */
+    language: string;
+    /** How the child parts relate ({@link PartSemantics}). */
+    partSemantics: PartSemantics;
+    /** The ordered child parts (draft requires 2 or more). */
+    parts: Part[];
+}
+/** The body tree: a cardinality-tagged union of {@link NullPart}, {@link SinglePart}, {@link ExternalPart}, {@link MultiPart}. */
+export type Part = NullPart | SinglePart | ExternalPart | MultiPart;
+/** Expiry directive (draft `Expiration = [relative: bool, time: uint .size 4]`). */
+export interface Expiration {
+    /** `true` = `time` is seconds relative to receipt; `false` = absolute UNIX time. */
+    relative: boolean;
+    /** The expiry time (seconds). */
+    time: number;
+}
+/** The MIMI message content structure (draft-ietf-mimi-content-08; see file header for the CDDL). */
+export interface MimiContent {
+    /** Per-message CSPRNG bytes (draft `salt`, 16 bytes) — unlinkability of the content hash. */
+    salt: Uint8Array;
+    /** 32-byte content-hash (MessageId) of a message this replaces (edit/delete/un-react), or `null`. */
+    replaces: Uint8Array | null;
+    /** Threading topic id (Tier 3; encoded, unsurfaced). Empty = none. */
+    topicId: Uint8Array;
+    /** Expiry directive (draft `Expiration`), or `null` for none. Tier 3; encoded, unsurfaced. */
+    expires: Expiration | null;
+    /** 32-byte content-hash (MessageId) of the reply target, or `null`. */
+    inReplyTo: Uint8Array | null;
+    /** Extension map (round-tripped opaquely). */
+    extensions: CborMap;
+    /** The message body tree (draft `NestedPart`). */
+    nestedPart: Part;
+}
+/**
+ * Schema bounds enforced on decode (DoS / abuse guard): max sibling parts in a {@link MultiPart}, and
+ * max part-tree depth. (draft-08 has no `lastSeen`, so there is no list bound here.)
+ */
+export declare const MIMI_LIMITS: {
+    readonly maxParts: 64;
+    readonly maxNesting: 8;
+};
+/**
+ * Encode a {@link MimiContent} to canonical CBOR bytes per the draft-08 wire layout.
+ * @param c - The content to encode.
+ * @returns Canonical CBOR bytes (stable for equal content — the basis for {@link contentHash}).
+ * @throws {Error} If a field carries an out-of-subset CBOR value (e.g. a non-integer number).
+ * @example
+ * ```ts
+ * const bytes = encodeMimiContent(myContent);
+ * const same  = decodeMimiContent(bytes); // round-trips
+ * ```
+ */
+export declare function encodeMimiContent(c: MimiContent): Uint8Array;
+/**
+ * Strict-decode + schema-validate canonical CBOR into a {@link MimiContent}. Fails closed on any
+ * structural or bounds violation (untrusted peer input — CLAUDE.md §1).
+ * @param bytes - The canonical CBOR content bytes (after unframing).
+ * @returns The validated {@link MimiContent}.
+ * @throws {Error} On a malformed structure, wrong field type, an unknown {@link Cardinality}, or a
+ *   {@link MIMI_LIMITS} bound exceeded. The error message never includes message plaintext.
+ * @example
+ * ```ts
+ * const content = decodeMimiContent(peerBytes); // throws on any tampering
+ * ```
+ */
+export declare function decodeMimiContent(bytes: Uint8Array): MimiContent;
+/**
+ * The MIMI content-hash: a 32-byte, MessageId-SHAPED reference value used to point at a message
+ * (reply / edit / delete / un-react). Per the file-header deviation note, we lack federation
+ * identities, so instead of draft-08's URI-prefixed input we compute
+ * `0x01 || sha256(encodeMimiContent(c))[0..30]` — the leading `0x01` is the SHA-256 hash-algorithm
+ * identifier, then the first 31 bytes of the SHA-256 over our canonical CBOR (which already includes
+ * the per-message `salt`). Structurally a real MIMI MessageId; stable across runtimes; salt-sensitive.
+ * The blind server never sees this. `replaces` / `inReplyTo` are populated with this value.
+ * @param c - The content to hash.
+ * @returns A 32-byte MessageId (`[0]` is `0x01`; `[1..31]` are `sha256(canonical CBOR)[0..30]`).
+ * @example
+ * ```ts
+ * const id = contentHash(myContent); // 32 bytes, id[0] === 0x01, salt-sensitive
+ * reply.inReplyTo = id;
+ * ```
+ */
+export declare function contentHash(c: MimiContent): Uint8Array;

package/dist/cjs/content/mimi-content.js

@@ -0,0 +1,289 @@
+"use strict";
+// MimiContent — secure-chat's message content format. IMPLEMENTS draft-ietf-mimi-content-08 (2 Mar
+// 2026), the message-content CDDL. The CBOR WIRE STRUCTURE below is draft-08-faithful with NO deviation
+// (the interop-readiness payoff); the ONE deliberate deviation is MessageId DERIVATION (we lack
+// federation identities) — documented in full at the bottom of this header.
+//
+// Where it sits: pure structure ABOVE the SecureChatCrypto seam and INSIDE the padding frame. Content
+// is a core concern, never crypto's. We encode/decode the FULL draft structure (so Tier-3 fields
+// round-trip today and surface later without rework); the hook surfaces Tier 2 (text / reply /
+// reaction / edit / delete). Decoded bytes are UNTRUSTED peer input: decodeMimiContent validates the
+// schema AFTER canonical CBOR-decoding and fails closed (CLAUDE.md §1).
+//
+// Wire CDDL (draft-ietf-mimi-content-08, the message-content section) — exactly what we encode/decode:
+//
+//   mimiContent = [salt:bstr.size 16, replaces:null/MessageId, topicId:bstr,
+//                  expires:null/Expiration, inReplyTo:null/MessageId,
+//                  mimiExtensions:extensions, nestedPart:NestedPart]      ; 7 elements
+//   MessageId   = bstr.size 32
+//   Expiration  = [relative:bool, time:uint.size 4]
+//   extensions  = { ? &(senderUri:1)^ => tstr, ? &(roomUri:2)^ => tstr, * otherKnown, * unknown }
+//                 name = int / tstr.size (1..255)   value = any.size (0..4095)
+//   NestedPart  = [disposition, language:tstr, (NullPart // SinglePart // ExternalPart // MultiPart)]
+//   NullPart    = (cardinality:nullpart)
+//   SinglePart  = (cardinality:single,  contentType:tstr, content:bstr)
+//   ExternalPart= (cardinality:external, contentType:tstr, url:tstr, expires:uint.size 4,
+//                  size:uint.size 8, encAlg:uint.size 2, key:bstr, nonce:bstr, aad:bstr,
+//                  hashAlg:uint.size 1, contentHash:bstr, description:tstr, filename:tstr)
+//   MultiPart   = (cardinality:multi, partSemantics, parts:[2* NestedPart])  ; ≥2 parts
+//   baseDispos: unspecified=0 render=1 reaction=2 profile=3 inline=4 icon=5 attachment=6 session=7 preview=8
+//   cardinality: nullpart=0 single=1 external=2 multi=3   partSemantics: chooseOne=0 singleUnit=1 processAll=2
+//   SHA-256 hash-algorithm identifier = 0x01
+//
+// Because NestedPart hoists `disposition` + `language` OUT of the variant, a single part encodes to the
+// CBOR array [disposition, language, cardinality, …variantFields]. Our TS `Part` types keep
+// `disposition`/`language` ON each variant (so the reducer can branch on `part.disposition ===
+// Disposition.Reaction` and builders can set it); the codec maps them to/from the wrapper positions.
+//
+// ── THE ONE DELIBERATE DEVIATION: MessageId derivation ───────────────────────────────────────────
+// draft-08 derives a MessageId from FEDERATION IDENTITIES:
+//     messageId = 0x01 || SHA256(senderUriLen || senderUri || roomUriLen || roomUri || message || salt)[0..30]
+// This SDK adopts the MIMI content FORMAT, not MIMI federation (design spec Goal A) — we have no
+// senderUri / roomUri. So `contentHash(content)` returns a 32-byte MessageId-SHAPED value:
+//     0x01 (SHA-256 hashAlg) || sha256(encodeMimiContent(content))[0..30]   (1 + 31 = 32 bytes)
+// — structurally a real MIMI MessageId; only the hash INPUT is simplified (our canonical CBOR, which
+// already includes the per-message `salt`, with no URI prefixes). `replaces`/`inReplyTo` carry THIS
+// value. This is the single upgrade-when-federation-lands deviation; the WIRE CBOR has none.
+//
+// Design-doc reconcile (FOLLOWING THE DRAFT; for the doc owner): the doc's top-level `lastSeen` list,
+// the per-Part `partIndex`, and `width`/`height`/`duration` on ExternalPart are NOT in draft-08 and are
+// DROPPED; the doc modeled `inReplyTo` as {hash, hashAlgorithm} but the draft uses a bare 32-byte
+// MessageId, so `inReplyTo` is now `Uint8Array | null` and the `MessageDerivedValue` type is removed.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIMI_LIMITS = exports.HashAlg = exports.PartSemantics = exports.Disposition = exports.Cardinality = void 0;
+exports.encodeMimiContent = encodeMimiContent;
+exports.decodeMimiContent = decodeMimiContent;
+exports.contentHash = contentHash;
+const cbor_js_1 = require("./cbor.js");
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+/**
+ * Part cardinality tag. Values per draft-ietf-mimi-content-08
+ * (`nullpart=0, single=1, external=2, multi=3`).
+ */
+exports.Cardinality = { Null: 0, Single: 1, External: 2, Multi: 3 };
+/**
+ * Part disposition (draft-ietf-mimi-content-08 `baseDispos`). `Reaction` distinguishes a reaction
+ * from a reply; `Attachment`/`Inline`/etc. drive client rendering.
+ */
+exports.Disposition = {
+    Unspecified: 0, Render: 1, Reaction: 2, Profile: 3, Inline: 4, Icon: 5,
+    Attachment: 6, Session: 7, Preview: 8,
+};
+/**
+ * {@link MultiPart} `partSemantics` — how a client treats the child parts (draft-ietf-mimi-content-08:
+ * `chooseOne=0, singleUnit=1, processAll=2`).
+ */
+exports.PartSemantics = { ChooseOne: 0, SingleUnit: 1, ProcessAll: 2 };
+/**
+ * Named-Information hash algorithm. SHA-256 is the only value we emit (identifier `0x01`, per
+ * draft-ietf-mimi-content-08).
+ */
+exports.HashAlg = { Sha256: 1 };
+/**
+ * Schema bounds enforced on decode (DoS / abuse guard): max sibling parts in a {@link MultiPart}, and
+ * max part-tree depth. (draft-08 has no `lastSeen`, so there is no list bound here.)
+ */
+exports.MIMI_LIMITS = { maxParts: 64, maxNesting: 8 };
+// ── encode ────────────────────────────────────────────────────────────────────
+function encodePart(p) {
+    // NestedPart = [disposition, language, …variant-starting-with-cardinality].
+    switch (p.cardinality) {
+        case exports.Cardinality.Null:
+            return [p.disposition, p.language, exports.Cardinality.Null];
+        case exports.Cardinality.Single:
+            return [p.disposition, p.language, exports.Cardinality.Single, p.contentType, p.content];
+        case exports.Cardinality.External:
+            return [
+                p.disposition, p.language, exports.Cardinality.External, p.contentType, p.url, p.expires, p.size,
+                p.encAlgorithm, p.key, p.nonce, p.aad, p.hashAlgorithm, p.contentHash, p.description, p.filename,
+            ];
+        case exports.Cardinality.Multi:
+            return [p.disposition, p.language, exports.Cardinality.Multi, p.partSemantics, p.parts.map(encodePart)];
+    }
+}
+function toCbor(c) {
+    return [
+        c.salt,
+        c.replaces, // bstr(32) | null
+        c.topicId,
+        c.expires ? [c.expires.relative, c.expires.time] : null, // Expiration | null
+        c.inReplyTo, // bstr(32) | null
+        c.extensions,
+        encodePart(c.nestedPart),
+    ];
+}
+/**
+ * Encode a {@link MimiContent} to canonical CBOR bytes per the draft-08 wire layout.
+ * @param c - The content to encode.
+ * @returns Canonical CBOR bytes (stable for equal content — the basis for {@link contentHash}).
+ * @throws {Error} If a field carries an out-of-subset CBOR value (e.g. a non-integer number).
+ * @example
+ * ```ts
+ * const bytes = encodeMimiContent(myContent);
+ * const same  = decodeMimiContent(bytes); // round-trips
+ * ```
+ */
+function encodeMimiContent(c) {
+    return (0, cbor_js_1.encode)(toCbor(c));
+}
+// ── decode + validate ───────────────────────────────────────────────────────
+function asArray(v, ctx) {
+    if (!Array.isArray(v))
+        throw new Error(`MimiContent: expected array (${ctx})`);
+    return v;
+}
+function asBytes(v, ctx) {
+    if (!(v instanceof Uint8Array))
+        throw new Error(`MimiContent: expected bytes (${ctx})`);
+    return v;
+}
+function asString(v, ctx) {
+    if (typeof v !== "string")
+        throw new Error(`MimiContent: expected string (${ctx})`);
+    return v;
+}
+function asInt(v, ctx) {
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw new Error(`MimiContent: expected int (${ctx})`);
+    return v;
+}
+function asBool(v, ctx) {
+    if (typeof v !== "boolean")
+        throw new Error(`MimiContent: expected bool (${ctx})`);
+    return v;
+}
+/**
+ * Exact wire-array length per cardinality (`[disposition, language, cardinality, …variant]`). Decode
+ * asserts this exactly so a part carrying TRAILING junk is rejected, not silently dropped (CLAUDE.md
+ * §1: fail closed — never skip the check).
+ */
+const PART_ARITY = {
+    [exports.Cardinality.Null]: 3, // disposition, language, cardinality
+    [exports.Cardinality.Single]: 5, // + contentType, content
+    // disposition, language, cardinality + 12 ExternalPart fields (contentType, url, expires, size,
+    // encAlg, key, nonce, aad, hashAlg, contentHash, description, filename) = 15. (decode reads a[14].)
+    [exports.Cardinality.External]: 15,
+    [exports.Cardinality.Multi]: 5, // + partSemantics, parts
+};
+function decodePart(v, depth) {
+    if (depth > exports.MIMI_LIMITS.maxNesting)
+        throw new Error("MimiContent: part nesting exceeds bounds");
+    const a = asArray(v, "part");
+    // NestedPart wrapper: [disposition, language, cardinality, …variant].
+    const disposition = asInt(a[0], "part.disposition");
+    const language = asString(a[1], "part.language");
+    const card = asInt(a[2], "part.cardinality");
+    // Fail closed on an unknown cardinality OR a wrong-length part array (trailing/missing elements).
+    const expectedArity = PART_ARITY[card];
+    if (expectedArity === undefined)
+        throw new Error(`MimiContent: unknown part cardinality ${card}`);
+    if (a.length !== expectedArity)
+        throw new Error(`MimiContent: wrong arity for cardinality ${card}`);
+    switch (card) {
+        case exports.Cardinality.Null:
+            return { cardinality: exports.Cardinality.Null, disposition, language };
+        case exports.Cardinality.Single:
+            return {
+                cardinality: exports.Cardinality.Single,
+                disposition,
+                language,
+                contentType: asString(a[3], "contentType"),
+                content: asBytes(a[4], "content"),
+            };
+        case exports.Cardinality.External:
+            return {
+                cardinality: exports.Cardinality.External,
+                disposition,
+                language,
+                contentType: asString(a[3], "contentType"),
+                url: asString(a[4], "url"),
+                expires: asInt(a[5], "expires"),
+                size: asInt(a[6], "size"),
+                encAlgorithm: asInt(a[7], "encAlgorithm"),
+                key: asBytes(a[8], "key"),
+                nonce: asBytes(a[9], "nonce"),
+                aad: asBytes(a[10], "aad"),
+                hashAlgorithm: asInt(a[11], "hashAlgorithm"),
+                contentHash: asBytes(a[12], "contentHash"),
+                description: asString(a[13], "description"),
+                filename: asString(a[14], "filename"),
+            };
+        case exports.Cardinality.Multi: {
+            const parts = asArray(a[4], "multi.parts");
+            // The draft requires 2 or more child parts; reject a degenerate multipart fail-closed.
+            if (parts.length < 2)
+                throw new Error("MimiContent: multipart requires 2+ parts");
+            if (parts.length > exports.MIMI_LIMITS.maxParts)
+                throw new Error("MimiContent: too many parts (bounds)");
+            return {
+                cardinality: exports.Cardinality.Multi,
+                disposition,
+                language,
+                partSemantics: asInt(a[3], "partSemantics"),
+                parts: parts.map((p) => decodePart(p, depth + 1)),
+            };
+        }
+        default:
+            throw new Error(`MimiContent: unknown part cardinality ${card}`);
+    }
+}
+/**
+ * Strict-decode + schema-validate canonical CBOR into a {@link MimiContent}. Fails closed on any
+ * structural or bounds violation (untrusted peer input — CLAUDE.md §1).
+ * @param bytes - The canonical CBOR content bytes (after unframing).
+ * @returns The validated {@link MimiContent}.
+ * @throws {Error} On a malformed structure, wrong field type, an unknown {@link Cardinality}, or a
+ *   {@link MIMI_LIMITS} bound exceeded. The error message never includes message plaintext.
+ * @example
+ * ```ts
+ * const content = decodeMimiContent(peerBytes); // throws on any tampering
+ * ```
+ */
+function decodeMimiContent(bytes) {
+    const a = asArray((0, cbor_js_1.decode)(bytes, { maxItems: exports.MIMI_LIMITS.maxParts * 4 }), "MimiContent");
+    if (a.length !== 7)
+        throw new Error("MimiContent: wrong top-level arity");
+    const replaces = a[1] === null ? null : asBytes(a[1], "replaces");
+    let expires = null;
+    if (a[3] !== null) {
+        const e = asArray(a[3], "expires");
+        expires = { relative: asBool(e[0], "expires.relative"), time: asInt(e[1], "expires.time") };
+    }
+    const inReplyTo = a[4] === null ? null : asBytes(a[4], "inReplyTo");
+    const ext = a[5];
+    if (!(ext instanceof Map))
+        throw new Error("MimiContent: extensions must be a map");
+    return {
+        salt: asBytes(a[0], "salt"),
+        replaces,
+        topicId: asBytes(a[2], "topicId"),
+        expires,
+        inReplyTo,
+        extensions: ext,
+        nestedPart: decodePart(a[6], 0),
+    };
+}
+/**
+ * The MIMI content-hash: a 32-byte, MessageId-SHAPED reference value used to point at a message
+ * (reply / edit / delete / un-react). Per the file-header deviation note, we lack federation
+ * identities, so instead of draft-08's URI-prefixed input we compute
+ * `0x01 || sha256(encodeMimiContent(c))[0..30]` — the leading `0x01` is the SHA-256 hash-algorithm
+ * identifier, then the first 31 bytes of the SHA-256 over our canonical CBOR (which already includes
+ * the per-message `salt`). Structurally a real MIMI MessageId; stable across runtimes; salt-sensitive.
+ * The blind server never sees this. `replaces` / `inReplyTo` are populated with this value.
+ * @param c - The content to hash.
+ * @returns A 32-byte MessageId (`[0]` is `0x01`; `[1..31]` are `sha256(canonical CBOR)[0..30]`).
+ * @example
+ * ```ts
+ * const id = contentHash(myContent); // 32 bytes, id[0] === 0x01, salt-sensitive
+ * reply.inReplyTo = id;
+ * ```
+ */
+function contentHash(c) {
+    const digest = (0, sha2_js_1.sha256)(encodeMimiContent(c));
+    const messageId = new Uint8Array(32);
+    messageId[0] = exports.HashAlg.Sha256; // 0x01 — the MessageId hashAlg prefix byte
+    messageId.set(digest.subarray(0, 31), 1); // first 31 SHA-256 bytes fill [1..31]
+    return messageId;
+}
+//# sourceMappingURL=mimi-content.js.map

package/dist/cjs/content/mimi-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mimi-content.js","sourceRoot":"","sources":["../../../src/content/mimi-content.ts"],"names":[],"mappings":"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"}

package/dist/cjs/context/secure-chat-context.d.ts

@@ -22,6 +22,15 @@ export interface SecureChatContextValue {
     resolveGroup: (conversationId: string) => Promise<GroupHandle | null>;
     /** Cache + persist a conversation's group handle (after createGroup / processWelcome). */
     rememberGroup: (conversationId: string, handle: GroupHandle) => Promise<void>;
+    /**
+     * Persist a conversation's CURRENT group state after an intra-epoch ratchet advance — i.e. an
+     * application message we just sent or received. Unlike {@link rememberGroup} it does NOT bump the
+     * version or notify listeners: an application message moves the (single-use, forward-secret) MLS
+     * ratchet but NOT the epoch, so consumers must not re-resolve the handle. Skipping this persist is
+     * the resend-replay bug — on reload the send ratchet rewinds to a consumed generation and the peer
+     * rejects the next message as a replay.
+     */
+    persistGroupState: (conversationId: string, handle: GroupHandle) => Promise<void>;
     /**
      * Current change-version for a conversation's group handle. Bumps every time the handle advances
      * (a join or a processed Commit), so consumers can detect "the group moved" without diffing handles.
@@ -52,9 +61,16 @@ export interface SecureChatProviderProps {
     accessToken?: string;
     /** Override token resolution (takes precedence over `accessToken`). */
     getAccessToken?: () => string | undefined;
-    /** Override the API base URL. Defaults to @agora-sdk/core `getApiBaseUrl()`. */
-    baseUrl?: string;
-    /** Override the socket origin. Defaults to @agora-sdk/core `getSocketUrl()`. */
+    /**
+     * API base URL including the version prefix (e.g. `https://api.example.com/v7`). Required — secure
+     * chat is a standalone transport and does not resolve a URL from any ambient SDK runtime. Read
+     * lazily per request, so re-passing a changed value takes effect on the next call.
+     */
+    baseUrl: string;
+    /**
+     * Socket.io origin for the `/secure` realtime namespace. Defaults to {@link baseUrl} (the client
+     * strips any path to the origin), so pass it only when the socket lives on a different host.
+     */
     socketUrl?: string;
     /**
      * Outbound message size-bucket padding policy (metadata hardening). `"ladder"` (default) pads each

package/dist/cjs/context/secure-chat-context.js

@@ -5,17 +5,21 @@ exports.useSecureChat = useSecureChat;
 const jsx_runtime_1 = require("react/jsx-runtime");
 // SecureChatProvider — wires transport + crypto + persistence for the secure-chat hooks.
 //
-// Sits INSIDE a ReplykeProvider: by default it resolves the API base URL and socket origin from
-// @agora-sdk/core's runtime singletons (getApiBaseUrl / getSocketUrl). Crypto AND the persistence
-// store are injected, keeping core platform- and library-agnostic. The provider builds a typed
-// SecureChatRepository over the store plus a cached resolveGroup/rememberGroup so the hooks become
-// self-sufficient (no need to thread a GroupHandle in by hand).
+// Standalone transport: the caller supplies the API base URL (and optional socket origin) directly —
+// this package has NO dependency on @agora-sdk/core. (It used to fall back to core's getApiBaseUrl /
+// getSocketUrl runtime singletons; that coupling existed only to auto-inherit a Replyke app's config,
+// and core's actual surface here was just two URL accessors. Requiring `baseUrl` makes secure chat a
+// self-contained E2EE transport usable in any app.) Crypto AND the persistence store are injected too,
+// keeping this layer platform- and library-agnostic. The provider builds a typed SecureChatRepository
+// over the store plus a cached resolveGroup/rememberGroup so the hooks become self-sufficient (no need
+// to thread a GroupHandle in by hand).
 const react_1 = require("react");
-const core_1 = require("@agora-sdk/core");
 const rest_js_1 = require("../transport/rest.js");
 const socket_js_1 = require("../transport/socket.js");
 const memory_store_js_1 = require("../persistence/memory-store.js");
 const repository_js_1 = require("../persistence/repository.js");
+const debug_js_1 = require("../util/debug.js");
+const log = (0, debug_js_1.createDebugLogger)("provider");
 const SecureChatContext = (0, react_1.createContext)(null);
 /**
  * Provides secure-chat transport, crypto, and persistence to the `useSecure*` hooks. Render inside a
@@ -38,13 +42,14 @@ function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessTo
     const rest = (0, react_1.useMemo)(() => new rest_js_1.SecureChatRestClient({
         projectId,
         getAccessToken: resolveToken,
-        getBaseUrl: () => baseUrl ?? (0, core_1.getApiBaseUrl)(),
+        getBaseUrl: () => baseUrl,
     }), [projectId, resolveToken, baseUrl]);
     const socket = (0, react_1.useMemo)(() => new socket_js_1.SecureChatSocketClient({
         projectId,
         getAccessToken: resolveToken,
-        getSocketUrl: () => socketUrl ?? (0, core_1.getSocketUrl)(),
-    }), [projectId, resolveToken, socketUrl]);
+        // Socket origin defaults to the REST base URL (the client strips the path to an origin).
+        getSocketUrl: () => socketUrl ?? baseUrl,
+    }), [projectId, resolveToken, socketUrl, baseUrl]);
     const resolvedStore = (0, react_1.useMemo)(() => store ?? new memory_store_js_1.MemoryStore(), [store]);
     const repo = (0, react_1.useMemo)(() => new repository_js_1.SecureChatRepository(resolvedStore), [resolvedStore]);
     // In-memory GroupHandle cache, keyed by conversationId. Survives re-renders via the ref.
@@ -62,11 +67,33 @@ function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessTo
         if (cached)
             return cached;
         const bytes = await repo.loadGroupState(conversationId);
-        if (!bytes)
+        if (!bytes) {
+            // No persisted group for this conversation: the recipient never joined (no Welcome processed),
+            // or local state was wiped. Renders as "waiting for key update" until a Welcome arrives.
+            log.debug("resolveGroup: no persisted group state", { conversationId });
             return null;
-        const handle = await crypto.importGroupState(bytes);
-        groupCache.current.set(conversationId, handle);
-        return handle;
+        }
+        try {
+            const handle = await crypto.importGroupState(bytes);
+            groupCache.current.set(conversationId, handle);
+            log.debug("resolveGroup: imported group from store", {
+                conversationId,
+                epoch: handle.epoch.toString(),
+                bytes: bytes.length,
+            });
+            return handle;
+        }
+        catch (err) {
+            // A persisted group that can't be re-imported is a black hole — it silently degrades to "no
+            // group" (a permanent "waiting for key update"). Surface it loudly so a reload-persistence or
+            // crypto-version-skew problem is visible instead of looking like an un-joined conversation.
+            log.debug("resolveGroup: importGroupState FAILED — group present but unreadable", {
+                conversationId,
+                bytes: bytes.length,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
     }, [repo, crypto]);
     const rememberGroup = (0, react_1.useCallback)(async (conversationId, handle) => {
         groupCache.current.set(conversationId, handle);
@@ -76,6 +103,17 @@ function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessTo
         groupVersion.current.set(conversationId, (groupVersion.current.get(conversationId) ?? 0) + 1);
         groupListeners.current.forEach((l) => l());
     }, [repo, crypto]);
+    const persistGroupState = (0, react_1.useCallback)(async (conversationId, handle) => {
+        // Re-export the now-advanced ratchet for THIS group and overwrite the persisted blob. The
+        // ratchet state lives in the crypto's internal per-group map (keyed by mlsGroupId), so exporting
+        // the same handle after a send/receive captures the advanced generation. Deliberately NO version
+        // bump and NO listener notify (cf. rememberGroup): an application message is intra-epoch, so a
+        // re-resolve would be wasted work and could churn buffered-row retries. The cache holds the same
+        // handle object the hook already uses, so re-setting it is idempotent.
+        groupCache.current.set(conversationId, handle);
+        const bytes = await crypto.exportGroupState(handle);
+        await repo.saveGroupState(conversationId, bytes);
+    }, [repo, crypto]);
     const getGroupVersion = (0, react_1.useCallback)((conversationId) => groupVersion.current.get(conversationId) ?? 0, []);
     const subscribeGroupChange = (0, react_1.useCallback)((listener) => {
         groupListeners.current.add(listener);
@@ -93,6 +131,7 @@ function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessTo
         repo,
         resolveGroup,
         rememberGroup,
+        persistGroupState,
         getGroupVersion,
         subscribeGroupChange,
         padding,
@@ -104,6 +143,7 @@ function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessTo
         repo,
         resolveGroup,
         rememberGroup,
+        persistGroupState,
         getGroupVersion,
         subscribeGroupChange,
         padding,