@novasamatech/statement-store 0.9.0 → 0.9.2

package/dist/helpers.d.ts

@@ -1,2 +1 @@
 export declare function toError(err: unknown): Error;
-export declare function nonNullable<T>(value: T): value is Exclude<NonNullable<T>, void>;

package/dist/helpers.js

@@ -7,6 +7,3 @@ export function toError(err) {
     }
     return new Error('Unknown error occurred.');
 }
-export function nonNullable(value) {
-    return value !== null && value !== undefined;
-}

package/dist/index.d.ts

@@ -4,7 +4,14 @@ export { SessionIdCodec, createSessionId } from './model/session.js';
 export type { AccountId, LocalSessionAccount, RemoteSessionAccount, SessionAccount } from './model/sessionAccount.js';
 export { AccountIdCodec, LocalSessionAccountCodec, RemoteSessionAccountCodec, createAccountId, createLocalSessionAccount, createRemoteSessionAccount, } from './model/sessionAccount.js';
 export type { Session } from './session/types.js';
+export type { SessionParams } from './session/session.js';
 export { createSession } from './session/session.js';
+export type { MultiDeviceSessionParams } from './session/multiDeviceSession.js';
+export { createMultiDeviceSession } from './session/multiDeviceSession.js';
+export type { DeviceTarget, Envelope } from './session/codec/envelope.js';
+export { createEnvelope } from './session/codec/envelope.js';
+export type { PeerRoster } from './session/codec/incomingTopics.js';
+export { createRequestChannel, createResponseChannel } from './session/codec/outgoingBody.js';
 export type { ResponseStatus } from './session/scale/statementData.js';
 export { Request, Response, ResponseCode, StatementData } from './session/scale/statementData.js';
 export type { StatementProver } from './session/statementProver.js';

package/dist/index.js

@@ -1,6 +1,9 @@
 export { SessionIdCodec, createSessionId } from './model/session.js';
 export { AccountIdCodec, LocalSessionAccountCodec, RemoteSessionAccountCodec, createAccountId, createLocalSessionAccount, createRemoteSessionAccount, } from './model/sessionAccount.js';
 export { createSession } from './session/session.js';
+export { createMultiDeviceSession } from './session/multiDeviceSession.js';
+export { createEnvelope } from './session/codec/envelope.js';
+export { createRequestChannel, createResponseChannel } from './session/codec/outgoingBody.js';
 export { Request, Response, ResponseCode, StatementData } from './session/scale/statementData.js';
 export { createSlotAccountProver, createSr25519Prover } from './session/statementProver.js';
 export { createEncryption } from './session/encyption.js';

package/dist/session/codec/decoder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Statement → {@link TransportEvent} decoding, transparent across all four
+ * `StatementData` variants.
+ *
+ * Every statement goes: verify proof → decrypt outer pairwise layer → decode
+ * `StatementData`. Single-device variants (tags 0/1) are used directly; multi-device
+ * variants (tags 2/3) are unwrapped through the {@link Envelope} first, then their inner
+ * `Request`/`Response` is decoded.
+ *
+ * Two directions, because our own envelopes carry no entry addressed to us:
+ *  - {@link StatementDecoder.decodePeer} — a peer's statement, decrypted with the topic's
+ *    encryption and unwrapped against the sending device's encryption pubkey.
+ *  - {@link StatementDecoder.decodeOwn} — one of our own statements read back from the
+ *    store during initialization, decrypted with our outgoing encryption and unwrapped
+ *    against a recipient device we wrapped it for.
+ *
+ * A statement whose outer layer decrypts but whose payload does not decode yields
+ * `undecodable` with a best-effort `requestId`, so the caller can still NACK the sender
+ * instead of leaving it waiting.
+ */
+import type { Statement } from '@novasamatech/sdk-statement';
+import type { ResultAsync } from 'neverthrow';
+import type { Encryption } from '../encyption.js';
+import type { ResponseStatus } from '../scale/statementData.js';
+import type { StatementProver } from '../statementProver.js';
+import type { DeviceTarget, Envelope } from './envelope.js';
+export type TransportEvent = {
+    tag: 'request';
+    requestId: string;
+    messages: Uint8Array[];
+    expiry: bigint | undefined;
+} | {
+    tag: 'response';
+    requestId: string;
+    responseCode: ResponseStatus;
+    expiry: bigint | undefined;
+}
+/**
+ * Outer decryption succeeded (so the sender is genuine) but the payload did not decode.
+ * `requestId` is recovered when possible so the sender can be NACKed; `null` otherwise.
+ */
+ | {
+    tag: 'undecodable';
+    requestId: string | null;
+};
+/** An event carrying an actual payload — everything except {@link TransportEvent} `undecodable`. */
+export type ReadableEvent = Extract<TransportEvent, {
+    tag: 'request' | 'response';
+}>;
+/** Everything needed to read statements arriving on one incoming topic. */
+export type IncomingTopicSpec = {
+    topic: Uint8Array;
+    /** Encryption pubkey of the device publishing here — the envelope unwrap counterparty. */
+    senderEncryptionPublicKey: Uint8Array;
+    /** Outer pairwise encryption for this topic. */
+    encryption: Encryption;
+};
+export type StatementDecoder = {
+    decodePeer(statement: Statement, spec: IncomingTopicSpec): ResultAsync<TransportEvent, Error>;
+    decodeOwn(statement: Statement, peerDevices: DeviceTarget[]): ResultAsync<TransportEvent, Error>;
+};
+export declare function createStatementDecoder({ prover, envelope, ownEncryption, }: {
+    prover: StatementProver;
+    /** Omit for a single-device session: multi-device variants then decode as `undecodable`. */
+    envelope?: Envelope;
+    /** Outer encryption of our OWN outgoing statements — used only by {@link StatementDecoder.decodeOwn}. */
+    ownEncryption: Encryption;
+}): StatementDecoder;

package/dist/session/codec/decoder.js

@@ -0,0 +1,96 @@
+/**
+ * Statement → {@link TransportEvent} decoding, transparent across all four
+ * `StatementData` variants.
+ *
+ * Every statement goes: verify proof → decrypt outer pairwise layer → decode
+ * `StatementData`. Single-device variants (tags 0/1) are used directly; multi-device
+ * variants (tags 2/3) are unwrapped through the {@link Envelope} first, then their inner
+ * `Request`/`Response` is decoded.
+ *
+ * Two directions, because our own envelopes carry no entry addressed to us:
+ *  - {@link StatementDecoder.decodePeer} — a peer's statement, decrypted with the topic's
+ *    encryption and unwrapped against the sending device's encryption pubkey.
+ *  - {@link StatementDecoder.decodeOwn} — one of our own statements read back from the
+ *    store during initialization, decrypted with our outgoing encryption and unwrapped
+ *    against a recipient device we wrapped it for.
+ *
+ * A statement whose outer layer decrypts but whose payload does not decode yields
+ * `undecodable` with a best-effort `requestId`, so the caller can still NACK the sender
+ * instead of leaving it waiting.
+ */
+import { err, errAsync, fromThrowable, ok } from 'neverthrow';
+import { Struct, str } from 'scale-ts';
+import { toError } from '../../helpers.js';
+import { Request, RequestDeviceInfo, Response, StatementData } from '../scale/statementData.js';
+const decodeStatementData = fromThrowable(StatementData.dec, toError);
+const decodeRequest = fromThrowable(Request.dec, toError);
+const decodeResponse = fromThrowable(Response.dec, toError);
+// Best-effort recovery of the requestId from a decrypted-but-undecodable payload. The
+// requestId is the first field after the enum tag, so it usually survives a corrupt body.
+// Only requests (tag 0) carry an id worth answering; anything else returns null.
+const RequestIdPrefix = Struct({ requestId: str });
+const decodeRequestIdPrefix = fromThrowable(
+// slice (a copy), not subarray: scale-ts decodes from the backing buffer start and
+// ignores a view's byteOffset, so a subarray would be read from the wrong position.
+(decrypted) => RequestIdPrefix.dec(decrypted.slice(1)).requestId, () => null);
+function recoverRequestId(decrypted) {
+    if (decrypted.length < 1 || decrypted[0] !== 0)
+        return null;
+    return decodeRequestIdPrefix(decrypted).unwrapOr(null);
+}
+function toRequestEvent(value, expiry) {
+    return { tag: 'request', requestId: value.requestId, messages: value.data, expiry };
+}
+function toResponseEvent(value, expiry) {
+    return { tag: 'response', requestId: value.requestId, responseCode: value.responseCode, expiry };
+}
+// An envelope we cannot open carries no recoverable requestId — the id lives inside it.
+const UNOPENABLE = { tag: 'undecodable', requestId: null };
+export function createStatementDecoder({ prover, envelope, ownEncryption, }) {
+    function decode(statement, encryption, unwrap) {
+        const data = statement.data;
+        if (!data)
+            return errAsync(new Error('decoder: statement carries no data'));
+        return prover
+            .verifyMessageProof(statement)
+            .andThen(verified => (verified ? ok() : err(new Error('decoder: invalid statement proof'))))
+            .andThen(() => encryption.decrypt(data))
+            .map(decrypted => toEvent(decrypted, statement.expiry, unwrap));
+    }
+    function toEvent(decrypted, expiry, unwrap) {
+        const decoded = decodeStatementData(decrypted);
+        if (decoded.isErr())
+            return { tag: 'undecodable', requestId: recoverRequestId(decrypted) };
+        const statementData = decoded.value;
+        switch (statementData.tag) {
+            case 'request':
+                return toRequestEvent(statementData.value, expiry);
+            case 'response':
+                return toResponseEvent(statementData.value, expiry);
+            case 'multiRequest':
+                if (!unwrap)
+                    return UNOPENABLE;
+                return unwrap(statementData.value.encryptedRequest, statementData.value.devicesInfo)
+                    .andThen(decodeRequest)
+                    .map(value => toRequestEvent(value, expiry))
+                    .unwrapOr(UNOPENABLE);
+            case 'multiResponse':
+                if (!unwrap)
+                    return UNOPENABLE;
+                return unwrap(statementData.value.encryptedResponse, statementData.value.devicesInfo)
+                    .andThen(decodeResponse)
+                    .map(value => toResponseEvent(value, expiry))
+                    .unwrapOr(UNOPENABLE);
+        }
+    }
+    return {
+        decodePeer(statement, spec) {
+            return decode(statement, spec.encryption, envelope
+                ? (payload, devicesInfo) => envelope.unwrapForOwnDevice(payload, devicesInfo, spec.senderEncryptionPublicKey)
+                : null);
+        },
+        decodeOwn(statement, peerDevices) {
+            return decode(statement, ownEncryption, envelope ? (payload, devicesInfo) => envelope.unwrapOwn(payload, devicesInfo, peerDevices) : null);
+        },
+    };
+}

package/dist/session/codec/decoder.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/codec/decoder.spec.js

@@ -0,0 +1,161 @@
+import { x25519 } from '@noble/curves/ed25519.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { ok, okAsync } from 'neverthrow';
+import { mergeUint8 } from 'polkadot-api/utils';
+import { compact, str } from 'scale-ts';
+import { describe, expect, it } from 'vitest';
+import { Request, Response, StatementData } from '../scale/statementData.js';
+import { createStatementDecoder } from './decoder.js';
+import { createEnvelope } from './envelope.js';
+const acceptingProver = {
+    generateMessageProof: statement => okAsync({ ...statement, proof: undefined }),
+    verifyMessageProof: () => okAsync(true),
+};
+const rejectingProver = { ...acceptingProver, verifyMessageProof: () => okAsync(false) };
+/** Identity encryption keeps the tests focused on decode paths, not on AEAD. */
+function passthroughEncryption() {
+    return { encrypt: data => ok(data), decrypt: data => ok(data) };
+}
+function createDevice() {
+    const encryptionPrivateKey = x25519.utils.randomSecretKey();
+    return {
+        statementAccountId: randomBytes(32),
+        encryptionPublicKey: x25519.getPublicKey(encryptionPrivateKey),
+        encryptionPrivateKey,
+    };
+}
+function envelopeFor(device) {
+    return createEnvelope({
+        ownStatementAccountId: device.statementAccountId,
+        ownEncryptionPrivateKey: device.encryptionPrivateKey,
+    });
+}
+function statementWith(data) {
+    return { expiry: 42n, data, topics: [], channel: `0x${'00'.repeat(32)}` };
+}
+function specFor(senderEncryptionPublicKey) {
+    return { topic: new Uint8Array(32), senderEncryptionPublicKey, encryption: passthroughEncryption() };
+}
+const MESSAGES = [new TextEncoder().encode('hello'), new TextEncoder().encode('world')];
+function singleDeviceDecoder(prover = acceptingProver) {
+    // No envelope — a single-device session cannot open multi-device variants.
+    return createStatementDecoder({ prover, ownEncryption: passthroughEncryption() });
+}
+describe('statement decoder', () => {
+    it('decodes a single-device request', async () => {
+        const data = StatementData.enc({ tag: 'request', value: { requestId: 'r1', data: MESSAGES } });
+        const event = (await singleDeviceDecoder().decodePeer(statementWith(data), specFor(randomBytes(32))))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'request', requestId: 'r1', messages: MESSAGES, expiry: 42n });
+    });
+    it('decodes a single-device response', async () => {
+        const data = StatementData.enc({ tag: 'response', value: { requestId: 'r1', responseCode: 'success' } });
+        const event = (await singleDeviceDecoder().decodePeer(statementWith(data), specFor(randomBytes(32))))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'response', requestId: 'r1', responseCode: 'success', expiry: 42n });
+    });
+    it('decodes a peer multiRequest addressed to this device', async () => {
+        const sender = createDevice();
+        const own = createDevice();
+        const inner = Request.enc({ requestId: 'r2', data: MESSAGES });
+        const wrapped = envelopeFor(sender).wrap(inner, [own])._unsafeUnwrap();
+        const data = StatementData.enc({
+            tag: 'multiRequest',
+            value: { encryptedRequest: wrapped.encryptedPayload, devicesInfo: wrapped.devicesInfo },
+        });
+        const decoder = createStatementDecoder({
+            prover: acceptingProver,
+            envelope: envelopeFor(own),
+            ownEncryption: passthroughEncryption(),
+        });
+        const event = (await decoder.decodePeer(statementWith(data), specFor(sender.encryptionPublicKey)))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'request', requestId: 'r2', messages: MESSAGES, expiry: 42n });
+    });
+    it('decodes a peer multiResponse addressed to this device', async () => {
+        const sender = createDevice();
+        const own = createDevice();
+        const inner = Response.enc({ requestId: 'r3', responseCode: 'success' });
+        const wrapped = envelopeFor(sender).wrap(inner, [own])._unsafeUnwrap();
+        const data = StatementData.enc({
+            tag: 'multiResponse',
+            value: { encryptedResponse: wrapped.encryptedPayload, devicesInfo: wrapped.devicesInfo },
+        });
+        const decoder = createStatementDecoder({
+            prover: acceptingProver,
+            envelope: envelopeFor(own),
+            ownEncryption: passthroughEncryption(),
+        });
+        const event = (await decoder.decodePeer(statementWith(data), specFor(sender.encryptionPublicKey)))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'response', requestId: 'r3', responseCode: 'success', expiry: 42n });
+    });
+    // The initialization-phase read-back that replaces a client-side outbox: our own
+    // envelope has no entry for us, so it is opened via a recipient device instead.
+    it('decodes our OWN multiRequest read back from the store', async () => {
+        const own = createDevice();
+        const peerA = createDevice();
+        const peerB = createDevice();
+        const peers = [peerA, peerB];
+        const inner = Request.enc({ requestId: 'own-1', data: MESSAGES });
+        const wrapped = envelopeFor(own).wrap(inner, peers)._unsafeUnwrap();
+        const data = StatementData.enc({
+            tag: 'multiRequest',
+            value: { encryptedRequest: wrapped.encryptedPayload, devicesInfo: wrapped.devicesInfo },
+        });
+        const decoder = createStatementDecoder({
+            prover: acceptingProver,
+            envelope: envelopeFor(own),
+            ownEncryption: passthroughEncryption(),
+        });
+        const event = (await decoder.decodeOwn(statementWith(data), peers))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'request', requestId: 'own-1', messages: MESSAGES, expiry: 42n });
+    });
+    it('reports an unopenable envelope as undecodable with no requestId', async () => {
+        const sender = createDevice();
+        const intended = createDevice();
+        const outsider = createDevice();
+        const inner = Request.enc({ requestId: 'r4', data: MESSAGES });
+        const wrapped = envelopeFor(sender).wrap(inner, [intended])._unsafeUnwrap();
+        const data = StatementData.enc({
+            tag: 'multiRequest',
+            value: { encryptedRequest: wrapped.encryptedPayload, devicesInfo: wrapped.devicesInfo },
+        });
+        const decoder = createStatementDecoder({
+            prover: acceptingProver,
+            envelope: envelopeFor(outsider),
+            ownEncryption: passthroughEncryption(),
+        });
+        const event = (await decoder.decodePeer(statementWith(data), specFor(sender.encryptionPublicKey)))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'undecodable', requestId: null });
+    });
+    // Decrypted but malformed: the requestId survives right after the enum tag, so the
+    // sender can still be NACKed rather than left waiting.
+    it('recovers the requestId from a decrypted-but-malformed request', async () => {
+        // tag(request) : requestId : a message-vector length that no bytes back up.
+        const malformed = mergeUint8([new Uint8Array([0]), str.enc('recover-me'), compact.enc(255)]);
+        const event = (await singleDeviceDecoder().decodePeer(statementWith(malformed), specFor(randomBytes(32))))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'undecodable', requestId: 'recover-me' });
+    });
+    it('reports garbage with no recoverable requestId as undecodable', async () => {
+        const event = (await singleDeviceDecoder().decodePeer(statementWith(new Uint8Array([9, 9, 9])), specFor(randomBytes(32))))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'undecodable', requestId: null });
+    });
+    it('fails a statement whose proof does not verify', async () => {
+        const data = StatementData.enc({ tag: 'request', value: { requestId: 'r5', data: MESSAGES } });
+        const result = await singleDeviceDecoder(rejectingProver).decodePeer(statementWith(data), specFor(randomBytes(32)));
+        expect(result.isErr()).toBe(true);
+    });
+    it('fails a statement carrying no data', async () => {
+        const result = await singleDeviceDecoder().decodePeer({ expiry: 1n, topics: [] }, specFor(randomBytes(32)));
+        expect(result.isErr()).toBe(true);
+    });
+    it('a single-device session cannot open multi-device variants', async () => {
+        const sender = createDevice();
+        const own = createDevice();
+        const inner = Request.enc({ requestId: 'r6', data: MESSAGES });
+        const wrapped = envelopeFor(sender).wrap(inner, [own])._unsafeUnwrap();
+        const data = StatementData.enc({
+            tag: 'multiRequest',
+            value: { encryptedRequest: wrapped.encryptedPayload, devicesInfo: wrapped.devicesInfo },
+        });
+        const event = (await singleDeviceDecoder().decodePeer(statementWith(data), specFor(sender.encryptionPublicKey)))._unsafeUnwrap();
+        expect(event).toEqual({ tag: 'undecodable', requestId: null });
+    });
+});

package/dist/session/codec/envelope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Multi-device statement envelope (mds.md §"Sending P2P Messages").
+ *
+ * A fresh 32-byte one-shot key encrypts the inner `Request`/`Response`; that key is then
+ * wrapped once per recipient device via X25519 key agreement between the sender's device
+ * encryption key and the recipient device's encryption public key:
+ *
+ *   encryptedPayload = aead(oneShotKey, inner)                      // key used RAW, no KDF
+ *   devicesInfo[i]   = { statementAccountId, encryptedKey }
+ *   encryptedKey     = encryption(x25519(ownEncPriv, deviceEncPub)).encrypt(oneShotKey)
+ *
+ * The one-shot key is already uniformly random, so it is used directly as the AEAD key —
+ * unlike {@link createEncryption}, which HKDFs its input because that input is a raw ECDH
+ * shared secret. This split matches Android (`MultiDeviceEnvelopeEncryption`) byte for byte.
+ *
+ * Three read paths:
+ *  - {@link Envelope.unwrapForOwnDevice} — a peer's envelope addressed to us.
+ *  - {@link Envelope.unwrapOwn} — OUR OWN envelope, read back from the store. The wrap
+ *    secret is symmetric, so we re-derive it against any recipient device we wrapped for.
+ *    This is what lets the statement store hold the outgoing-request state through a
+ *    restart (base-spec.md §"Session Initialization Phase") instead of a client-side outbox.
+ *  - single-device sessions pass no envelope at all; tags 2/3 then decode as `undecodable`.
+ */
+import { Result } from 'neverthrow';
+import type { CodecType } from 'scale-ts';
+import type { RequestDeviceInfo } from '../scale/statementData.js';
+export type DeviceTarget = {
+    /** 32-byte sr25519 statement account id — the device's identifier on the wire. */
+    statementAccountId: Uint8Array;
+    /** 32-byte X25519 device encryption public key. */
+    encryptionPublicKey: Uint8Array;
+};
+/**
+ * Both fields are fixed-width on the wire, and `Bytes(32)` zero-pads anything shorter — a
+ * malformed roster entry would otherwise yield a valid-looking statement addressed to the
+ * wrong device, or a topic no peer ever writes to, with no error anywhere.
+ */
+export declare function isValidDevice(device: DeviceTarget): boolean;
+type DeviceEntry = CodecType<typeof RequestDeviceInfo>;
+type WrappedEnvelope = {
+    encryptedPayload: Uint8Array;
+    devicesInfo: DeviceEntry[];
+};
+export type Envelope = {
+    wrap(plaintext: Uint8Array, recipients: DeviceTarget[]): Result<WrappedEnvelope, Error>;
+    /** Decrypt an envelope a peer addressed to this device. */
+    unwrapForOwnDevice(encryptedPayload: Uint8Array, devicesInfo: DeviceEntry[], senderEncryptionPublicKey: Uint8Array): Result<Uint8Array, Error>;
+    /** Decrypt an envelope WE produced, using any recipient device we wrapped it for. */
+    unwrapOwn(encryptedPayload: Uint8Array, devicesInfo: DeviceEntry[], peerDevices: DeviceTarget[]): Result<Uint8Array, Error>;
+};
+export declare function createEnvelope({ ownStatementAccountId, ownEncryptionPrivateKey, }: {
+    ownStatementAccountId: Uint8Array;
+    ownEncryptionPrivateKey: Uint8Array;
+}): Envelope;
+export {};

package/dist/session/codec/envelope.js

@@ -0,0 +1,115 @@
+/**
+ * Multi-device statement envelope (mds.md §"Sending P2P Messages").
+ *
+ * A fresh 32-byte one-shot key encrypts the inner `Request`/`Response`; that key is then
+ * wrapped once per recipient device via X25519 key agreement between the sender's device
+ * encryption key and the recipient device's encryption public key:
+ *
+ *   encryptedPayload = aead(oneShotKey, inner)                      // key used RAW, no KDF
+ *   devicesInfo[i]   = { statementAccountId, encryptedKey }
+ *   encryptedKey     = encryption(x25519(ownEncPriv, deviceEncPub)).encrypt(oneShotKey)
+ *
+ * The one-shot key is already uniformly random, so it is used directly as the AEAD key —
+ * unlike {@link createEncryption}, which HKDFs its input because that input is a raw ECDH
+ * shared secret. This split matches Android (`MultiDeviceEnvelopeEncryption`) byte for byte.
+ *
+ * Three read paths:
+ *  - {@link Envelope.unwrapForOwnDevice} — a peer's envelope addressed to us.
+ *  - {@link Envelope.unwrapOwn} — OUR OWN envelope, read back from the store. The wrap
+ *    secret is symmetric, so we re-derive it against any recipient device we wrapped for.
+ *    This is what lets the statement store hold the outgoing-request state through a
+ *    restart (base-spec.md §"Session Initialization Phase") instead of a client-side outbox.
+ *  - single-device sessions pass no envelope at all; tags 2/3 then decode as `undecodable`.
+ */
+import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { Result, err, fromThrowable } from 'neverthrow';
+import { mergeUint8 } from 'polkadot-api/utils';
+import { toError } from '../../helpers.js';
+import { createEncryption } from '../encyption.js';
+/** One-shot symmetric key length. Mirrors Android's `MessageEncryption` (32 bytes). */
+const ONE_SHOT_KEY_BYTES = 32;
+/** AEAD nonce length. Same 12 bytes for AES-GCM and ChaCha20-Poly1305. */
+const AEAD_NONCE_BYTES = 12;
+const ACCOUNT_ID_BYTES = 32;
+const PUBLIC_KEY_BYTES = 32;
+/**
+ * Both fields are fixed-width on the wire, and `Bytes(32)` zero-pads anything shorter — a
+ * malformed roster entry would otherwise yield a valid-looking statement addressed to the
+ * wrong device, or a topic no peer ever writes to, with no error anywhere.
+ */
+export function isValidDevice(device) {
+    return (device.statementAccountId.length === ACCOUNT_ID_BYTES && device.encryptionPublicKey.length === PUBLIC_KEY_BYTES);
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+// The one-shot key is uniformly random already, so it keys the AEAD directly.
+const aeadEncrypt = fromThrowable((key, plaintext) => {
+    const nonce = randomBytes(AEAD_NONCE_BYTES);
+    return mergeUint8([nonce, chacha20poly1305(key, nonce).encrypt(plaintext)]);
+}, toError);
+const aeadDecrypt = fromThrowable((key, encrypted) => {
+    const nonce = encrypted.slice(0, AEAD_NONCE_BYTES);
+    const cipherText = encrypted.slice(AEAD_NONCE_BYTES);
+    return chacha20poly1305(key, nonce).decrypt(cipherText);
+}, toError);
+/**
+ * `@noble` aborts on an all-zero (small-order) X25519 result per RFC 7748, so a hostile
+ * device key fails loudly here rather than yielding a predictable key (RFC-0004 §1).
+ */
+const deviceEncryption = fromThrowable((ownEncryptionPrivateKey, peerEncryptionPublicKey) => createEncryption(x25519.getSharedSecret(ownEncryptionPrivateKey, peerEncryptionPublicKey)), toError);
+export function createEnvelope({ ownStatementAccountId, ownEncryptionPrivateKey, }) {
+    // Unwrapping a key against a given peer device pubkey — the same derivation the wrap
+    // side uses, which is why `unwrapOwn` works at all.
+    function unwrapKeyAgainst(peerEncryptionPublicKey, encryptedKey) {
+        return deviceEncryption(ownEncryptionPrivateKey, peerEncryptionPublicKey).andThen(encryption => encryption.decrypt(encryptedKey));
+    }
+    return {
+        wrap(plaintext, recipients) {
+            if (recipients.length === 0) {
+                return err(new Error('envelope: cannot wrap without recipient devices'));
+            }
+            const malformed = recipients.find(recipient => !isValidDevice(recipient));
+            if (malformed) {
+                return err(new Error(`envelope: recipient device is malformed (statementAccountId ${malformed.statementAccountId.length.toString()} bytes, encryptionPublicKey ${malformed.encryptionPublicKey.length.toString()} bytes; both must be 32)`));
+            }
+            const oneShotKey = randomBytes(ONE_SHOT_KEY_BYTES);
+            return Result.combine(recipients.map(recipient => deviceEncryption(ownEncryptionPrivateKey, recipient.encryptionPublicKey)
+                .andThen(encryption => encryption.encrypt(oneShotKey))
+                .map(encryptedKey => ({
+                statementAccountId: recipient.statementAccountId,
+                encryptedKey,
+            })))).andThen(devicesInfo => aeadEncrypt(oneShotKey, plaintext).map(encryptedPayload => ({ encryptedPayload, devicesInfo })));
+        },
+        unwrapForOwnDevice(encryptedPayload, devicesInfo, senderEncryptionPublicKey) {
+            const ownEntry = devicesInfo.find(entry => bytesEqual(entry.statementAccountId, ownStatementAccountId));
+            if (!ownEntry) {
+                return err(new Error('envelope: no entry addressed to this device'));
+            }
+            return unwrapKeyAgainst(senderEncryptionPublicKey, ownEntry.encryptedKey).andThen(oneShotKey => aeadDecrypt(oneShotKey, encryptedPayload));
+        },
+        unwrapOwn(encryptedPayload, devicesInfo, peerDevices) {
+            // Any recipient entry works: we wrapped every one of them with our own private key,
+            // so re-deriving x25519(ownPriv, thatDevicePub) reproduces the wrap secret exactly.
+            for (const device of peerDevices) {
+                const entry = devicesInfo.find(candidate => bytesEqual(candidate.statementAccountId, device.statementAccountId));
+                if (!entry)
+                    continue;
+                const unwrapped = unwrapKeyAgainst(device.encryptionPublicKey, entry.encryptedKey).andThen(oneShotKey => aeadDecrypt(oneShotKey, encryptedPayload));
+                // A stale roster entry can fail to unwrap while a newer one still succeeds, so
+                // keep trying the remaining devices rather than failing on the first mismatch.
+                if (unwrapped.isOk())
+                    return unwrapped;
+            }
+            return err(new Error('envelope: no known peer device entry to unwrap own payload'));
+        },
+    };
+}

package/dist/session/codec/envelope.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/codec/envelope.spec.js

@@ -0,0 +1,114 @@
+import { x25519 } from '@noble/curves/ed25519.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { describe, expect, it } from 'vitest';
+import { createEnvelope } from './envelope.js';
+function createDevice() {
+    const encryptionPrivateKey = x25519.utils.randomSecretKey();
+    return {
+        statementAccountId: randomBytes(32),
+        encryptionPublicKey: x25519.getPublicKey(encryptionPrivateKey),
+        encryptionPrivateKey,
+    };
+}
+function envelopeFor(device) {
+    return createEnvelope({
+        ownStatementAccountId: device.statementAccountId,
+        ownEncryptionPrivateKey: device.encryptionPrivateKey,
+    });
+}
+const PLAINTEXT = new TextEncoder().encode('inner Request bytes');
+describe('multi-device envelope', () => {
+    it('a recipient device opens the envelope addressed to it', () => {
+        const sender = createDevice();
+        const recipientA = createDevice();
+        const recipientB = createDevice();
+        const wrapped = envelopeFor(sender).wrap(PLAINTEXT, [recipientA, recipientB])._unsafeUnwrap();
+        expect(wrapped.devicesInfo).toHaveLength(2);
+        for (const recipient of [recipientA, recipientB]) {
+            const opened = envelopeFor(recipient)
+                .unwrapForOwnDevice(wrapped.encryptedPayload, wrapped.devicesInfo, sender.encryptionPublicKey)
+                ._unsafeUnwrap();
+            expect(opened).toEqual(PLAINTEXT);
+        }
+    });
+    // The premise the whole "no client-side outbox" design rests on: the per-device wrap
+    // secret is x25519(senderPriv, recipientPub), so the SENDER can re-derive it for any
+    // recipient and read its own envelope back out of the statement store.
+    it('the sender reads back its own envelope via any recipient it wrapped for', () => {
+        const sender = createDevice();
+        const recipientA = createDevice();
+        const recipientB = createDevice();
+        const recipients = [recipientA, recipientB];
+        const senderEnvelope = envelopeFor(sender);
+        const wrapped = senderEnvelope.wrap(PLAINTEXT, recipients)._unsafeUnwrap();
+        expect(senderEnvelope.unwrapOwn(wrapped.encryptedPayload, wrapped.devicesInfo, recipients)._unsafeUnwrap()).toEqual(PLAINTEXT);
+        // …and with only the second recipient known, so the loop is genuinely per-device.
+        expect(senderEnvelope.unwrapOwn(wrapped.encryptedPayload, wrapped.devicesInfo, [recipientB])._unsafeUnwrap()).toEqual(PLAINTEXT);
+    });
+    it('skips a stale roster entry and opens via a device that still matches', () => {
+        const sender = createDevice();
+        const live = createDevice();
+        // Same account id as `live`, but a rotated encryption key — its unwrap must fail and
+        // the loop must keep going rather than give up on the first mismatch.
+        const rotated = createDevice();
+        const stale = {
+            statementAccountId: rotated.statementAccountId,
+            encryptionPublicKey: createDevice().encryptionPublicKey,
+        };
+        const senderEnvelope = envelopeFor(sender);
+        const wrapped = senderEnvelope.wrap(PLAINTEXT, [rotated, live])._unsafeUnwrap();
+        expect(senderEnvelope.unwrapOwn(wrapped.encryptedPayload, wrapped.devicesInfo, [stale, live])._unsafeUnwrap()).toEqual(PLAINTEXT);
+    });
+    it('rejects a device that is not a recipient', () => {
+        const sender = createDevice();
+        const recipient = createDevice();
+        const outsider = createDevice();
+        const wrapped = envelopeFor(sender).wrap(PLAINTEXT, [recipient])._unsafeUnwrap();
+        expect(envelopeFor(outsider)
+            .unwrapForOwnDevice(wrapped.encryptedPayload, wrapped.devicesInfo, sender.encryptionPublicKey)
+            .isErr()).toBe(true);
+    });
+    it('rejects the right device holding the wrong sender key', () => {
+        const sender = createDevice();
+        const impostor = createDevice();
+        const recipient = createDevice();
+        const wrapped = envelopeFor(sender).wrap(PLAINTEXT, [recipient])._unsafeUnwrap();
+        expect(envelopeFor(recipient)
+            .unwrapForOwnDevice(wrapped.encryptedPayload, wrapped.devicesInfo, impostor.encryptionPublicKey)
+            .isErr()).toBe(true);
+    });
+    it('rejects a tampered payload (AEAD tag)', () => {
+        const sender = createDevice();
+        const recipient = createDevice();
+        const wrapped = envelopeFor(sender).wrap(PLAINTEXT, [recipient])._unsafeUnwrap();
+        const tampered = Uint8Array.from(wrapped.encryptedPayload);
+        const last = tampered.length - 1;
+        tampered[last] = (tampered[last] ?? 0) ^ 0xff;
+        expect(envelopeFor(recipient).unwrapForOwnDevice(tampered, wrapped.devicesInfo, sender.encryptionPublicKey).isErr()).toBe(true);
+    });
+    // Both fields are fixed-width on the wire and Bytes(32) zero-pads, so a short value would
+    // otherwise produce a statement addressed to a device that does not exist.
+    it.each([
+        [
+            'statementAccountId',
+            { statementAccountId: randomBytes(20), encryptionPublicKey: createDevice().encryptionPublicKey },
+        ],
+        ['encryptionPublicKey', { statementAccountId: randomBytes(32), encryptionPublicKey: randomBytes(20) }],
+    ])('refuses to wrap for a recipient with a malformed %s', (_field, recipient) => {
+        const result = envelopeFor(createDevice()).wrap(PLAINTEXT, [recipient]);
+        expect(result.isErr()).toBe(true);
+        expect(result._unsafeUnwrapErr().message).toContain('malformed');
+    });
+    it('refuses to wrap without recipients', () => {
+        expect(envelopeFor(createDevice()).wrap(PLAINTEXT, []).isErr()).toBe(true);
+    });
+    it('produces a fresh one-shot key per wrap', () => {
+        const sender = createDevice();
+        const recipient = createDevice();
+        const senderEnvelope = envelopeFor(sender);
+        const first = senderEnvelope.wrap(PLAINTEXT, [recipient])._unsafeUnwrap();
+        const second = senderEnvelope.wrap(PLAINTEXT, [recipient])._unsafeUnwrap();
+        expect(first.encryptedPayload).not.toEqual(second.encryptedPayload);
+        expect(first.devicesInfo[0].encryptedKey).not.toEqual(second.devicesInfo[0].encryptedKey);
+    });
+});