@agora-sdk/secure-chat-core 0.3.0 → 0.5.0

package/dist/cjs/util/padding.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How aggressively to pad outbound message plaintext.
+ *
+ * - `"ladder"` — round the framed length up to the next size bucket (the default; blunts length
+ *   fingerprinting).
+ * - `"none"` — still frame the message (so unpadding stays uniform across clients) but add no extra
+ *   bytes. Use only when bandwidth matters more than traffic-shape privacy.
+ */
+export type PaddingPolicy = "ladder" | "none";
+/**
+ * Round a framed byte length up to the next size bucket: the smallest ladder rung
+ * (32, 64, … , 8192) that is ≥ `n`, or — above the ladder — the next multiple of 8192.
+ *
+ * @param n - The unpadded framed length (header + content) in bytes.
+ * @returns The bucket size to pad up to (always ≥ 32, always ≥ `n`).
+ */
+export declare function nextBucket(n: number): number;
+/**
+ * Wrap message content in a size-bucket padding frame for encryption. The output is
+ * `[version][contentLen][content][zero pad]`; under `"ladder"` its length is one of the fixed buckets
+ * from {@link nextBucket}. Padding bytes are zeros — they ride inside the MLS ciphertext, so they need
+ * not be random.
+ *
+ * @param content - The plaintext bytes to send (e.g. `utf8ToBytes(text)`).
+ * @param policy - The {@link PaddingPolicy}; defaults to `"ladder"`.
+ * @returns The framed, padded bytes to hand to `crypto.encryptMessage`.
+ */
+export declare function padPlaintext(content: Uint8Array, policy?: PaddingPolicy): Uint8Array;
+/**
+ * Recover the original content from a {@link padPlaintext} frame after decryption. Validates the version
+ * byte and bounds-checks the declared length, then slices off the header and trailing zero padding.
+ *
+ * @param frame - The decrypted frame bytes (from `crypto.decryptMessage`).
+ * @returns The original content bytes.
+ * @throws {Error} On a frame that is too short, carries an unknown version, or declares a length that
+ *   overruns the buffer — a successfully-authenticated MLS message with a bad frame is a real
+ *   framing/version mismatch, so the caller fails closed rather than rendering raw padded bytes.
+ */
+export declare function unpadPlaintext(frame: Uint8Array): Uint8Array;

package/dist/cjs/util/padding.js

@@ -0,0 +1,80 @@
+"use strict";
+// Message size-bucket padding — a metadata-hardening frame applied to plaintext BEFORE MLS encryption.
+//
+// Where it sits in the blind-server model: the server (and any DB/network observer) is trusted to relay
+// ciphertext but learns *envelope* metadata in the Signal model — including ciphertext SIZE. Raw chat
+// text encrypts to a ciphertext whose length tracks the message length, leaking traffic shape. We wrap
+// the plaintext in a self-describing frame and zero-pad it up to a fixed bucket ladder, so short
+// messages collapse into a few sizes. MLS then encrypts the frame, so the ciphertext inherits the
+// bucketing (modulo a constant MLS framing overhead). This is pure byte-shuffling — NO crypto, no keys
+// — and the frame is symmetric: every client pads on send and unpads on receive identically.
+//
+// Frame layout: [version:1B = 1][contentLen:uint32 BE][content bytes][zero padding → bucket].
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextBucket = nextBucket;
+exports.padPlaintext = padPlaintext;
+exports.unpadPlaintext = unpadPlaintext;
+/** The smallest bucket; also the floor for an empty message (a 5-byte header → bucket 32). */
+const LADDER = [32, 64, 128, 256, 512, 1024, 2048, 4096, 8192];
+/** Above the ladder we round up to multiples of this (the largest ladder rung). */
+const STEP = 8192;
+/** Frame header: 1 version byte + a 4-byte big-endian content length. */
+const HEADER = 5;
+/** Frame format version, bound as the first byte so the codec can evolve without ambiguity. */
+const VERSION = 1;
+/**
+ * Round a framed byte length up to the next size bucket: the smallest ladder rung
+ * (32, 64, … , 8192) that is ≥ `n`, or — above the ladder — the next multiple of 8192.
+ *
+ * @param n - The unpadded framed length (header + content) in bytes.
+ * @returns The bucket size to pad up to (always ≥ 32, always ≥ `n`).
+ */
+function nextBucket(n) {
+    for (const b of LADDER)
+        if (n <= b)
+            return b;
+    return Math.ceil(n / STEP) * STEP;
+}
+/**
+ * Wrap message content in a size-bucket padding frame for encryption. The output is
+ * `[version][contentLen][content][zero pad]`; under `"ladder"` its length is one of the fixed buckets
+ * from {@link nextBucket}. Padding bytes are zeros — they ride inside the MLS ciphertext, so they need
+ * not be random.
+ *
+ * @param content - The plaintext bytes to send (e.g. `utf8ToBytes(text)`).
+ * @param policy - The {@link PaddingPolicy}; defaults to `"ladder"`.
+ * @returns The framed, padded bytes to hand to `crypto.encryptMessage`.
+ */
+function padPlaintext(content, policy = "ladder") {
+    const framed = HEADER + content.length;
+    const target = policy === "ladder" ? nextBucket(framed) : framed;
+    const out = new Uint8Array(target); // zero-filled → the padding is already in place
+    out[0] = VERSION;
+    out[1] = (content.length >>> 24) & 0xff;
+    out[2] = (content.length >>> 16) & 0xff;
+    out[3] = (content.length >>> 8) & 0xff;
+    out[4] = content.length & 0xff;
+    out.set(content, HEADER);
+    return out;
+}
+/**
+ * Recover the original content from a {@link padPlaintext} frame after decryption. Validates the version
+ * byte and bounds-checks the declared length, then slices off the header and trailing zero padding.
+ *
+ * @param frame - The decrypted frame bytes (from `crypto.decryptMessage`).
+ * @returns The original content bytes.
+ * @throws {Error} On a frame that is too short, carries an unknown version, or declares a length that
+ *   overruns the buffer — a successfully-authenticated MLS message with a bad frame is a real
+ *   framing/version mismatch, so the caller fails closed rather than rendering raw padded bytes.
+ */
+function unpadPlaintext(frame) {
+    if (frame.length < HEADER)
+        throw new Error("secure-chat: padding frame too short");
+    if (frame[0] !== VERSION)
+        throw new Error(`secure-chat: unsupported padding frame version ${frame[0]}`);
+    const len = (frame[1] << 24) | (frame[2] << 16) | (frame[3] << 8) | frame[4];
+    if (len < 0 || HEADER + len > frame.length)
+        throw new Error("secure-chat: padding frame length out of range");
+    return frame.slice(HEADER, HEADER + len);
+}
+//# sourceMappingURL=padding.js.map

package/dist/cjs/util/padding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"padding.js","sourceRoot":"","sources":["../../../src/util/padding.ts"],"names":[],"mappings":";AAAA,uGAAuG;AACvG,EAAE;AACF,wGAAwG;AACxG,sGAAsG;AACtG,uGAAuG;AACvG,iGAAiG;AACjG,kGAAkG;AAClG,uGAAuG;AACvG,6FAA6F;AAC7F,EAAE;AACF,8FAA8F;;AA4B9F,gCAGC;AAYD,oCAWC;AAYD,wCAMC;AAtED,8FAA8F;AAC9F,MAAM,MAAM,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AACxE,mFAAmF;AACnF,MAAM,IAAI,GAAG,IAAI,CAAC;AAClB,yEAAyE;AACzE,MAAM,MAAM,GAAG,CAAC,CAAC;AACjB,+FAA+F;AAC/F,MAAM,OAAO,GAAG,CAAC,CAAC;AAYlB;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,CAAS;IAClC,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,YAAY,CAAC,OAAmB,EAAE,SAAwB,QAAQ;IAChF,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACvC,MAAM,MAAM,GAAG,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjE,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,gDAAgD;IACpF,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACjB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;IACvC,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/B,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACzB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,KAAiB;IAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACnF,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxG,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7E,IAAI,GAAG,GAAG,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IAC9G,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC;AAC3C,CAAC"}

package/dist/cjs/util/safety-number.d.ts

@@ -0,0 +1,27 @@
+import type { GroupMemberIdentity } from "@agora-sdk/secure-chat-crypto";
+/** A derived safety number, in the forms a UI needs. */
+export interface SafetyNumber {
+    /** All 60 decimal digits with no separators. */
+    digits: string;
+    /** The 60 digits as 12 groups of 5 (for display / read-aloud). */
+    groups: string[];
+    /** The raw combined fingerprint bytes (sorted-concatenated per-party hashes) — e.g. for a QR code. */
+    fingerprint: Uint8Array;
+}
+/**
+ * Derive the safety number for two parties from their public identities. The result is **symmetric** —
+ * `computeSafetyNumber(a, b)` equals `computeSafetyNumber(b, a)` — because the two per-party
+ * fingerprints are sorted before concatenation. Uses WebCrypto SHA-256 (available in browsers and
+ * Node 18+).
+ *
+ * @param a - One party's `{ deviceId, signaturePublicKey }` (e.g. the local device).
+ * @param b - The other party's identity (e.g. the remote peer).
+ * @returns The {@link SafetyNumber} (60 digits, 12 groups of 5, plus raw fingerprint bytes).
+ *
+ * @example
+ * ```ts
+ * const { groups } = await computeSafetyNumber(localIdentity, peerIdentity);
+ * // groups → ["12345", "67890", … 12 of them]; compare with the peer out-of-band.
+ * ```
+ */
+export declare function computeSafetyNumber(a: GroupMemberIdentity, b: GroupMemberIdentity): Promise<SafetyNumber>;

package/dist/cjs/util/safety-number.js

@@ -0,0 +1,84 @@
+"use strict";
+// Safety number — a human-comparable fingerprint of two devices' identity keys (key verification).
+//
+// Where it sits in the blind-server model: the server is blind but UNTRUSTED, so it could in principle
+// hand a victim a KeyPackage carrying an attacker's signature key (a classic active MITM on a TOFU
+// system). A safety number lets two users confirm out-of-band (read aloud / compare on screen / scan a
+// QR) that they actually hold each other's real identity keys. It is derived ONLY from public
+// signature keys + device ids — no secrets — and is symmetric: both sides compute the same number.
+//
+// Shape (Signal-style): each party's identity is hashed into a 30-digit number; the two are sorted (so
+// the result is order-independent) and concatenated into 60 decimal digits, shown as 12 groups of 5.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSafetyNumber = computeSafetyNumber;
+/** Format/version byte bound into the hash so the derivation can evolve unambiguously. */
+const VERSION = 0;
+/** Hash iterations per party. Public-key fingerprints don't need KDF-grade work; this is a fixed,
+ *  app-wide constant purely so every Agora client derives an identical number (interop, not secrecy). */
+const ITERATIONS = 1024;
+/** Bytes of the final hash consumed: 6 chunks × 5 bytes → 6 × 5 digits = 30 digits per party. */
+const CHUNKS = 6;
+const CHUNK_BYTES = 5;
+const utf8 = (s) => new TextEncoder().encode(s);
+function concat(...parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+async function sha256(bytes) {
+    // Cast to BufferSource: our Uint8Array is always ArrayBuffer-backed, but the lib type is the wider
+    // Uint8Array<ArrayBufferLike> (which could be SharedArrayBuffer) that digest() won't accept directly.
+    return new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+}
+/** Encode one 5-byte chunk as a 5-digit decimal string (40-bit big-endian value mod 100000). */
+function chunkToDigits(hash, offset) {
+    // 2**40 < 2**53, so plain Number arithmetic is exact here.
+    let value = 0;
+    for (let i = 0; i < CHUNK_BYTES; i++)
+        value = value * 256 + hash[offset + i];
+    return (value % 100000).toString().padStart(5, "0");
+}
+/** Per-party fingerprint: an iterated hash of (version || pubkey || deviceId), then 30 digits + the
+ *  truncated hash bytes. Signal-shaped (the key is re-mixed in each round). */
+async function partyFingerprint(party) {
+    const key = party.signaturePublicKey;
+    let hash = concat(Uint8Array.of(VERSION), key, utf8(party.deviceId));
+    for (let i = 0; i < ITERATIONS; i++)
+        hash = await sha256(concat(hash, key));
+    let digits = "";
+    for (let c = 0; c < CHUNKS; c++)
+        digits += chunkToDigits(hash, c * CHUNK_BYTES);
+    return { digits, bytes: hash.slice(0, CHUNKS * CHUNK_BYTES) };
+}
+/**
+ * Derive the safety number for two parties from their public identities. The result is **symmetric** —
+ * `computeSafetyNumber(a, b)` equals `computeSafetyNumber(b, a)` — because the two per-party
+ * fingerprints are sorted before concatenation. Uses WebCrypto SHA-256 (available in browsers and
+ * Node 18+).
+ *
+ * @param a - One party's `{ deviceId, signaturePublicKey }` (e.g. the local device).
+ * @param b - The other party's identity (e.g. the remote peer).
+ * @returns The {@link SafetyNumber} (60 digits, 12 groups of 5, plus raw fingerprint bytes).
+ *
+ * @example
+ * ```ts
+ * const { groups } = await computeSafetyNumber(localIdentity, peerIdentity);
+ * // groups → ["12345", "67890", … 12 of them]; compare with the peer out-of-band.
+ * ```
+ */
+async function computeSafetyNumber(a, b) {
+    const [fpA, fpB] = await Promise.all([partyFingerprint(a), partyFingerprint(b)]);
+    // Sort so the number is the same regardless of who is "a" vs "b".
+    const [first, second] = fpA.digits <= fpB.digits ? [fpA, fpB] : [fpB, fpA];
+    const digits = first.digits + second.digits;
+    const groups = [];
+    for (let i = 0; i < digits.length; i += 5)
+        groups.push(digits.slice(i, i + 5));
+    return { digits, groups, fingerprint: concat(first.bytes, second.bytes) };
+}
+//# sourceMappingURL=safety-number.js.map

package/dist/cjs/util/safety-number.js.map

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

package/dist/esm/backup/passphrase-strength.d.ts

@@ -0,0 +1,22 @@
+/** The outcome of {@link estimatePassphraseStrength}: a coarse 0–4 score plus display copy. */
+export interface PassphraseStrength {
+    /** 0 (weakest) … 4 (strongest) — for a 5-segment meter. */
+    score: 0 | 1 | 2 | 3 | 4;
+    /** A short human label for the score (e.g. "Weak", "Strong"). */
+    label: string;
+    /** A specific reason the passphrase is weak, when applicable (e.g. a common password). */
+    warning?: string;
+}
+/**
+ * Estimate the strength of a backup passphrase for a strength meter.
+ *
+ * @param passphrase - The candidate passphrase (never logged or sent anywhere).
+ * @returns A {@link PassphraseStrength} with a 0–4 score, a label, and an optional warning.
+ *
+ * @example
+ * ```ts
+ * const { score, label, warning } = estimatePassphraseStrength(input);
+ * // render a 5-segment meter from `score`, show `warning` if present.
+ * ```
+ */
+export declare function estimatePassphraseStrength(passphrase: string): PassphraseStrength;

package/dist/esm/backup/passphrase-strength.js

@@ -0,0 +1,72 @@
+// Passphrase-strength estimator for backup UX.
+//
+// Why this exists (CLAUDE.md #1 + spec §16.5): the blind server stores the passphrase-encrypted
+// backup blob, so a weak passphrase is offline-brute-forceable on a DB exfil. The real argon2id KDF
+// raises the cost per guess, but it can't rescue a guessable passphrase — so we nudge the user toward
+// a strong one at entry time. This is a deliberately small, dependency-free heuristic (length +
+// character-class diversity + a common-password penalty), NOT a substitute for zxcvbn-grade entropy
+// estimation. It runs purely client-side and never logs or transmits the passphrase.
+const LABELS = ["Very weak", "Weak", "Fair", "Strong", "Very strong"];
+// A tiny set of the most-guessed passwords/substrings. Not exhaustive — a guardrail against the
+// obvious, not a real dictionary check.
+const COMMON = [
+    "password", "passw0rd", "12345", "123456", "qwerty", "letmein", "admin", "welcome",
+    "iloveyou", "abc123", "hunter2", "monkey", "dragon", "trustno1", "secret",
+];
+/**
+ * Estimate the strength of a backup passphrase for a strength meter.
+ *
+ * @param passphrase - The candidate passphrase (never logged or sent anywhere).
+ * @returns A {@link PassphraseStrength} with a 0–4 score, a label, and an optional warning.
+ *
+ * @example
+ * ```ts
+ * const { score, label, warning } = estimatePassphraseStrength(input);
+ * // render a 5-segment meter from `score`, show `warning` if present.
+ * ```
+ */
+export function estimatePassphraseStrength(passphrase) {
+    const pw = passphrase ?? "";
+    if (pw.length === 0)
+        return { score: 0, label: LABELS[0] };
+    const lower = pw.toLowerCase();
+    const hitsCommon = COMMON.some((c) => lower.includes(c));
+    // Character-class diversity.
+    let classes = 0;
+    if (/[a-z]/.test(pw))
+        classes++;
+    if (/[A-Z]/.test(pw))
+        classes++;
+    if (/[0-9]/.test(pw))
+        classes++;
+    if (/[^a-zA-Z0-9]/.test(pw))
+        classes++;
+    // Length is the dominant factor (passphrases >> complex-but-short passwords).
+    let score = 0;
+    if (pw.length >= 8)
+        score++;
+    if (pw.length >= 12)
+        score++;
+    if (pw.length >= 16)
+        score++;
+    // Diversity adds at most one step, and only once there's some length.
+    if (classes >= 3 && pw.length >= 8)
+        score++;
+    // A short, single-class passphrase never rates above "weak".
+    if (pw.length < 8 || classes <= 1)
+        score = Math.min(score, 1);
+    // A recognizably common password is capped hard regardless of shape.
+    if (hitsCommon)
+        score = Math.min(score, 1);
+    const clamped = Math.max(0, Math.min(4, score));
+    return {
+        score: clamped,
+        label: LABELS[clamped],
+        warning: hitsCommon
+            ? "This looks like a common password — choose something less guessable."
+            : clamped <= 1
+                ? "Use a longer passphrase (4+ random words) with mixed character types."
+                : undefined,
+    };
+}
+//# sourceMappingURL=passphrase-strength.js.map

package/dist/esm/backup/passphrase-strength.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passphrase-strength.js","sourceRoot":"","sources":["../../../src/backup/passphrase-strength.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,gGAAgG;AAChG,oGAAoG;AACpG,sGAAsG;AACtG,gGAAgG;AAChG,oGAAoG;AACpG,qFAAqF;AAYrF,MAAM,MAAM,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAU,CAAC;AAE/E,gGAAgG;AAChG,wCAAwC;AACxC,MAAM,MAAM,GAAG;IACb,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS;IAClF,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ;CAC1E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAAkB;IAC3D,MAAM,EAAE,GAAG,UAAU,IAAI,EAAE,CAAC;IAC5B,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAE3D,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD,6BAA6B;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,8EAA8E;IAC9E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC;QAAE,KAAK,EAAE,CAAC;IAC5B,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE;QAAE,KAAK,EAAE,CAAC;IAC7B,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE;QAAE,KAAK,EAAE,CAAC;IAC7B,sEAAsE;IACtE,IAAI,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC;QAAE,KAAK,EAAE,CAAC;IAE5C,6DAA6D;IAC7D,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,IAAI,CAAC;QAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE9D,qEAAqE;IACrE,IAAI,UAAU;QAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE3C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAgC,CAAC;IAC/E,OAAO;QACL,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC;QACtB,OAAO,EAAE,UAAU;YACjB,CAAC,CAAC,sEAAsE;YACxE,CAAC,CAAC,OAAO,IAAI,CAAC;gBACZ,CAAC,CAAC,uEAAuE;gBACzE,CAAC,CAAC,SAAS;KAChB,CAAC;AACJ,CAAC"}

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

@@ -4,6 +4,7 @@ import { SecureChatRestClient } from "../transport/rest.js";
 import { SecureChatSocketClient } from "../transport/socket.js";
 import { SecureChatStore } from "../persistence/store.js";
 import { SecureChatRepository } from "../persistence/repository.js";
+import { PaddingPolicy } from "../util/padding.js";
 /**
  * The value exposed by {@link useSecureChat}: shared transport clients, the injected crypto, the
  * persistence repository, the group-handle resolver, and the active project id.
@@ -31,6 +32,11 @@ export interface SecureChatContextValue {
      * @returns An unsubscribe function.
      */
     subscribeGroupChange: (listener: () => void) => () => void;
+    /**
+     * Outbound message size-bucket padding policy. `useSecureMessages` pads plaintext to this before
+     * encryption so ciphertext size leaks less; defaults to `"ladder"`.
+     */
+    padding: PaddingPolicy;
     /** The Agora project id these clients are scoped to. */
     projectId: string;
 }
@@ -50,6 +56,11 @@ export interface SecureChatProviderProps {
     baseUrl?: string;
     /** Override the socket origin. Defaults to @agora-sdk/core `getSocketUrl()`. */
     socketUrl?: string;
+    /**
+     * Outbound message size-bucket padding policy (metadata hardening). `"ladder"` (default) pads each
+     * message up to a fixed size bucket so ciphertext length leaks less; `"none"` frames without padding.
+     */
+    padding?: PaddingPolicy;
     children: React.ReactNode;
 }
 /**
@@ -66,7 +77,7 @@ export interface SecureChatProviderProps {
  * </SecureChatProvider>
  * ```
  */
-export declare function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessToken, baseUrl, socketUrl, children, }: SecureChatProviderProps): React.JSX.Element;
+export declare function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessToken, baseUrl, socketUrl, padding, children, }: SecureChatProviderProps): React.JSX.Element;
 /**
  * Access the nearest {@link SecureChatContextValue}.
  *

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

@@ -27,7 +27,7 @@ const SecureChatContext = createContext(null);
  * </SecureChatProvider>
  * ```
  */
-export function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessToken, baseUrl, socketUrl, children, }) {
+export function SecureChatProvider({ crypto, projectId, store, accessToken, getAccessToken, baseUrl, socketUrl, padding = "ladder", children, }) {
     const tokenRef = useRef(accessToken);
     tokenRef.current = accessToken;
     const resolveToken = useMemo(() => getAccessToken ?? (() => tokenRef.current), [getAccessToken]);
@@ -91,6 +91,7 @@ export function SecureChatProvider({ crypto, projectId, store, accessToken, getA
         rememberGroup,
         getGroupVersion,
         subscribeGroupChange,
+        padding,
         projectId,
     }), [
         rest,
@@ -101,6 +102,7 @@ export function SecureChatProvider({ crypto, projectId, store, accessToken, getA
         rememberGroup,
         getGroupVersion,
         subscribeGroupChange,
+        padding,
         projectId,
     ]);
     return _jsx(SecureChatContext.Provider, { value: value, children: children });

package/dist/esm/context/secure-chat-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"secure-chat-context.js","sourceRoot":"","sources":["../../../src/context/secure-chat-context.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"secure-chat-context.js","sourceRoot":"","sources":["../../../src/context/secure-chat-context.tsx"],"names":[],"mappings":"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"}

package/dist/esm/contract/index.d.ts

@@ -1,150 +1,2 @@
-export type SecureConversationType = "dm" | "group" | "channel";
-export type SecureMemberRole = "admin" | "member";
-export type SecureHandshakeKind = "welcome" | "commit" | "proposal";
-/** A Welcome targeted at the ONE device whose claimed KeyPackage was consumed. */
-export interface WelcomeEnvelope {
-    targetDeviceId: string;
-    payload: string;
-    epoch: string;
-}
-/** A Commit/Proposal broadcast to the whole group (no target device). */
-export interface HandshakeBlob {
-    payload: string;
-    epoch: string;
-}
-export interface RegisterDeviceBody {
-    deviceId: string;
-    displayName?: string | null;
-    signaturePublicKey: string;
-    credential: string;
-    ciphersuite: number;
-}
-export interface PublishKeyPackagesBody {
-    keyPackages: {
-        keyPackageRef: string;
-        keyPackage: string;
-        ciphersuite: number;
-        expiresAt?: string | null;
-    }[];
-}
-export interface CreateSecureConversationBody {
-    type: SecureConversationType;
-    mlsGroupId: string;
-    spaceId?: string | null;
-    name?: string | null;
-    memberUserIds?: string[];
-    welcomes?: WelcomeEnvelope[];
-}
-export interface AddSecureMemberBody {
-    userId: string;
-    commit: HandshakeBlob;
-    welcomes: WelcomeEnvelope[];
-}
-export interface RemoveSecureMemberBody {
-    commit: HandshakeBlob;
-}
-export interface SendSecureMessageBody {
-    ciphertext: string;
-    epoch: string;
-    senderDeviceId: string;
-    contentType?: string | null;
-}
-export interface UploadKeyBackupBody {
-    deviceId?: string | null;
-    blob: string;
-    nonce: string;
-    kdf: "argon2id" | "pbkdf2";
-    kdfParams: Record<string, unknown>;
-    cipher: "xchacha20poly1305" | "aes-256-gcm";
-    version: number;
-}
-export interface SecureDeviceModel {
-    id: string;
-    projectId: string;
-    userId: string;
-    deviceId: string;
-    displayName: string | null;
-    signaturePublicKey: string;
-    credential: string;
-    ciphersuite: number;
-    revokedAt: string | null;
-    lastSeenAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface SecureKeyPackageClaim {
-    deviceId: string;
-    keyPackageRef: string;
-    keyPackage: string;
-    ciphersuite: number;
-}
-export interface SecureConversationMemberModel {
-    id: string;
-    projectId: string;
-    conversationId: string;
-    userId: string;
-    role: SecureMemberRole;
-    isActive: boolean;
-    joinedAtEpoch: string | null;
-    lastReadAt: string | null;
-    leftAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface SecureConversationModel {
-    id: string;
-    projectId: string;
-    type: SecureConversationType;
-    mlsGroupId: string;
-    spaceId: string | null;
-    currentEpoch: string;
-    name: string | null;
-    createdById: string | null;
-    lastMessageAt: string | null;
-    memberCount?: number;
-    unreadCount?: number;
-    currentMember?: SecureConversationMemberModel;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface SecureMessageModel {
-    id: string;
-    projectId: string;
-    conversationId: string;
-    senderUserId: string | null;
-    senderDeviceId: string | null;
-    epoch: string;
-    ciphertext: string;
-    contentType: string;
-    createdAt: string;
-}
-export interface SecureHandshakeModel {
-    id: string;
-    seq: string;
-    kind: SecureHandshakeKind;
-    conversationId: string;
-    epoch: string;
-    payload: string;
-    senderDeviceId: string | null;
-    targetDeviceId: string | null;
-}
-export interface SecureKeyBackupModel {
-    id: string;
-    projectId: string;
-    userId: string;
-    deviceId: string | null;
-    blob: string;
-    nonce: string;
-    kdf: string;
-    kdfParams: Record<string, unknown>;
-    cipher: string;
-    version: number;
-    createdAt: string;
-    updatedAt: string;
-}
-/** Standard error envelope: `{ error, code, field? }` with `secure-chat/*` codes. */
-export interface SecureChatErrorBody {
-    error: string;
-    code: string;
-    field?: string;
-}
+export type { SecureDeviceModel, SecureKeyPackageClaim, SecureConversationMemberModel, SecureConversationModel, SecureMessageModel, SecureHandshakeModel, SecureKeyBackupModel, } from "@agora-server/contract";
+export type { RegisterDeviceBody, PublishKeyPackagesBody, CreateSecureConversationBody, AddSecureMemberBody, RemoveSecureMemberBody, SendSecureMessageBody, UploadKeyBackupBody, WelcomeEnvelope, HandshakeBlob, } from "@agora-server/contract";

package/dist/esm/contract/index.js

@@ -1,15 +1,16 @@
-// Secure-chat wire contract — stand-in for @agora-server/contract (the Apache-2.0 server contract).
+// Secure-chat wire types — re-exported from the published `@agora-server/contract` (Apache-2.0).
 //
-// Mirrors the response models + request bodies of agora-server's
-// `packages/contract/src/secure-chat.ts`. That package is the source of truth (zod + TS); the
-// client only needs the TypeScript shapes, so this copy is types-only.
+// The dependency arrow is **SDK → contract**: agora-server owns the wire contract, this SDK depends
+// on it. This module used to hold a byte-faithful *copy* of the types (a stand-in until the contract
+// published); now that `@agora-server/contract` is published, it is a thin **type-only re-export** so
+// there is exactly one source of truth and zero drift. The internal import path
+// (`../contract/index.js`) is kept stable so call sites don't churn, and the re-export is scoped to
+// the secure-chat surface (not the contract's reactions/pagination/etc.).
 //
-// ⚠️ Keep this byte-faithful to the server contract. The arrow is SDK → contract: once
-// `@agora-server/contract` is published, DELETE this file and `import type { ... } from "@agora-server/contract"`.
-// Do NOT publish a separate `@agora-sdk/secure-chat-contract` (that would invert the dependency —
-// see STATUS.md). Do not let this copy drift in the meantime.
+// Type-only on purpose: `@agora-server/contract` is ESM-only, but these `export type` re-exports are
+// erased from the emitted JS, so core's dual ESM/CJS build never `require()`s it at runtime.
 //
-// Wire conventions: every binary value is **base64** (the server stores/relays opaque blobs and
-// never parses them); MLS epochs are **decimal strings** (u64 exceeds JS safe-int range).
+// Wire conventions (owned by the contract): every binary value is **base64**; MLS epochs are
+// **decimal strings** (u64 exceeds JS safe-int range).
 export {};
 //# sourceMappingURL=index.js.map

package/dist/esm/contract/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/index.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,EAAE;AACF,iEAAiE;AACjE,8FAA8F;AAC9F,uEAAuE;AACvE,EAAE;AACF,uFAAuF;AACvF,mHAAmH;AACnH,kGAAkG;AAClG,8DAA8D;AAC9D,EAAE;AACF,gGAAgG;AAChG,0FAA0F"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,EAAE;AACF,oGAAoG;AACpG,qGAAqG;AACrG,sGAAsG;AACtG,gFAAgF;AAChF,oGAAoG;AACpG,0EAA0E;AAC1E,EAAE;AACF,qGAAqG;AACrG,6FAA6F;AAC7F,EAAE;AACF,6FAA6F;AAC7F,uDAAuD"}