@novasamatech/statement-store 0.8.12 → 0.9.1

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);
+    });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * The set of topics a session listens on, and the keys needed to read each one.
+ *
+ * Single-device sessions listen on exactly one topic — `SessionId(B, A)`, keyed by the
+ * pairwise shared secret. Multi-device sessions listen on one topic PER PEER DEVICE:
+ * `SessionId(D(B'), A)` keyed by `x25519(ownIdentityChatPriv, D(B').encPub)`, the
+ * receive-side mirror of the sender's `SessionId(D(A), B)` (mds.md).
+ *
+ * The set is observable because a peer's device roster changes at runtime
+ * (`deviceAdded`/`deviceRemoved`). The driver opens ONE `matchAny` subscription over the
+ * whole set and re-opens it when the set changes — rather than one subscription per
+ * device, which grows as contacts × devices.
+ */
+import type { SessionAccount } from '../../model/sessionAccount.js';
+import type { IncomingTopicSpec } from './decoder.js';
+import type { DeviceTarget } from './envelope.js';
+export type PeerRoster = {
+    current(): DeviceTarget[];
+    subscribe(callback: (devices: DeviceTarget[]) => void): VoidFunction;
+};
+export type IncomingTopics = {
+    current(): IncomingTopicSpec[];
+    /** Fires when the topic set changes. Returns an unsubscribe handle. */
+    subscribe(callback: (specs: IncomingTopicSpec[]) => void): VoidFunction;
+};
+/** One fixed topic — the single-device case. */
+export declare function createStaticTopics(spec: IncomingTopicSpec): IncomingTopics;
+/**
+ * One topic per peer device, recomputed whenever the roster changes.
+ *
+ * Derivation per device `D(B')`:
+ *   K       = x25519(ownIdentityChatPrivateKey, D(B').encryptionPublicKey)
+ *   topic   = SessionId(D(B'), A)  — sender is the peer device, receiver is our identity
+ */
+export declare function createRosterTopics({ localIdentity, remotePin, ownIdentityChatPrivateKey, peerRoster, }: {
+    localIdentity: SessionAccount;
+    /**
+     * The peer IDENTITY's pin. A device inherits the pin of the identity it belongs to, so
+     * this is what goes in the sender slot of `SessionIdParam` — matching what the peer used
+     * when it published (Android `RealIncomingTopicsProviderFactory`, `pin = remoteAccount.pin`).
+     * Getting this wrong yields a topic the peer never writes to, and messages simply never arrive.
+     */
+    remotePin: string | undefined;
+    ownIdentityChatPrivateKey: Uint8Array;
+    peerRoster: PeerRoster;
+}): IncomingTopics;

package/dist/session/codec/incomingTopics.js

@@ -0,0 +1,69 @@
+/**
+ * The set of topics a session listens on, and the keys needed to read each one.
+ *
+ * Single-device sessions listen on exactly one topic — `SessionId(B, A)`, keyed by the
+ * pairwise shared secret. Multi-device sessions listen on one topic PER PEER DEVICE:
+ * `SessionId(D(B'), A)` keyed by `x25519(ownIdentityChatPriv, D(B').encPub)`, the
+ * receive-side mirror of the sender's `SessionId(D(A), B)` (mds.md).
+ *
+ * The set is observable because a peer's device roster changes at runtime
+ * (`deviceAdded`/`deviceRemoved`). The driver opens ONE `matchAny` subscription over the
+ * whole set and re-opens it when the set changes — rather than one subscription per
+ * device, which grows as contacts × devices.
+ */
+import { x25519 } from '@noble/curves/ed25519.js';
+import { createSessionId } from '../../model/session.js';
+import { createEncryption } from '../encyption.js';
+import { isValidDevice } from './envelope.js';
+/** One fixed topic — the single-device case. */
+export function createStaticTopics(spec) {
+    const specs = [spec];
+    return {
+        current: () => specs,
+        subscribe: () => () => undefined,
+    };
+}
+/**
+ * One topic per peer device, recomputed whenever the roster changes.
+ *
+ * Derivation per device `D(B')`:
+ *   K       = x25519(ownIdentityChatPrivateKey, D(B').encryptionPublicKey)
+ *   topic   = SessionId(D(B'), A)  — sender is the peer device, receiver is our identity
+ */
+export function createRosterTopics({ localIdentity, remotePin, ownIdentityChatPrivateKey, peerRoster, }) {
+    function toSpecs(devices) {
+        return devices.flatMap(device => {
+            // A malformed entry would derive a topic no peer writes to; skip it rather than
+            // listening on a dead one.
+            if (!isValidDevice(device))
+                return [];
+            let sharedSecret;
+            try {
+                // Throws on a small-order peer key (RFC 7748); a malformed roster entry must not
+                // take down the whole topic set, so it is skipped instead.
+                sharedSecret = x25519.getSharedSecret(ownIdentityChatPrivateKey, device.encryptionPublicKey);
+            }
+            catch {
+                return [];
+            }
+            const remoteDevice = { accountId: device.statementAccountId, pin: remotePin };
+            return [
+                {
+                    topic: createSessionId(sharedSecret, remoteDevice, localIdentity),
+                    senderEncryptionPublicKey: device.encryptionPublicKey,
+                    encryption: createEncryption(sharedSecret),
+                },
+            ];
+        });
+    }
+    let specs = toSpecs(peerRoster.current());
+    return {
+        current: () => specs,
+        subscribe(callback) {
+            return peerRoster.subscribe(devices => {
+                specs = toSpecs(devices);
+                callback(specs);
+            });
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Builds the statement body for an outgoing request/response.
+ *
+ * Two wire formats behind one interface — single-device (`StatementData.request`/
+ * `.response`) and multi-device (`.multiRequest`/`.multiResponse`, wrapped per recipient
+ * device). Fixed at session construction; the driver never branches on format.
+ *
+ * The builder is also the session's SIZE ORACLE. The driver builds the body it is about
+ * to submit and measures `body.data.length`, so AEAD expansion and per-device envelope
+ * fan-out are counted by construction — the two things a pre-encryption byte estimate
+ * misses, and the reason a multi-device batch cannot be sized from raw message bytes.
+ * On the happy path the measured body is the one submitted, so the check costs nothing.
+ */
+import type { Result } from 'neverthrow';
+import type { SessionId } from '../../model/session.js';
+import type { Encryption } from '../encyption.js';
+import type { ResponseStatus } from '../scale/statementData.js';
+import type { DeviceTarget, Envelope } from './envelope.js';
+export type StatementBody = {
+    channel: Uint8Array;
+    topics: Uint8Array[];
+    data: Uint8Array;
+};
+export type OutgoingBodyBuilder = {
+    buildRequest(requestId: string, messages: Uint8Array[]): Result<StatementBody, Error>;
+    buildResponse(requestId: string, responseCode: ResponseStatus): Result<StatementBody, Error>;
+};
+export declare function createRequestChannel(sessionId: Uint8Array): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+export declare function createResponseChannel(sessionId: Uint8Array): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/**
+ * Omit `multiDevice` for the single-device format (`StatementData.request`/`.response`
+ * straight under the pairwise encryption). Supply it to wrap the inner `Request`/`Response`
+ * for every recipient device first (mds.md §"Sending P2P Messages"); the outer encryption
+ * layer is the same either way.
+ *
+ * `recipients` is a thunk so a peer roster change is picked up on the next submit without
+ * rebuilding the session.
+ */
+export declare function createBodyBuilder({ topic, encryption, multiDevice, }: {
+    topic: SessionId;
+    encryption: Encryption;
+    multiDevice?: {
+        envelope: Envelope;
+        recipients: () => DeviceTarget[];
+    };
+}): OutgoingBodyBuilder;

package/dist/session/codec/outgoingBody.js

@@ -0,0 +1,64 @@
+/**
+ * Builds the statement body for an outgoing request/response.
+ *
+ * Two wire formats behind one interface — single-device (`StatementData.request`/
+ * `.response`) and multi-device (`.multiRequest`/`.multiResponse`, wrapped per recipient
+ * device). Fixed at session construction; the driver never branches on format.
+ *
+ * The builder is also the session's SIZE ORACLE. The driver builds the body it is about
+ * to submit and measures `body.data.length`, so AEAD expansion and per-device envelope
+ * fan-out are counted by construction — the two things a pre-encryption byte estimate
+ * misses, and the reason a multi-device batch cannot be sized from raw message bytes.
+ * On the happy path the measured body is the one submitted, so the check costs nothing.
+ */
+import { fromThrowable } from 'neverthrow';
+import { khash, stringToBytes } from '../../crypto.js';
+import { toError } from '../../helpers.js';
+import { Request, RequestDeviceInfo, Response, StatementData } from '../scale/statementData.js';
+const REQUEST_LABEL = stringToBytes('request');
+const RESPONSE_LABEL = stringToBytes('response');
+const encodeStatementData = fromThrowable(StatementData.enc, toError);
+const encodeRequest = fromThrowable(Request.enc, toError);
+const encodeResponse = fromThrowable(Response.enc, toError);
+export function createRequestChannel(sessionId) {
+    return khash(sessionId, REQUEST_LABEL);
+}
+export function createResponseChannel(sessionId) {
+    return khash(sessionId, RESPONSE_LABEL);
+}
+/**
+ * Omit `multiDevice` for the single-device format (`StatementData.request`/`.response`
+ * straight under the pairwise encryption). Supply it to wrap the inner `Request`/`Response`
+ * for every recipient device first (mds.md §"Sending P2P Messages"); the outer encryption
+ * layer is the same either way.
+ *
+ * `recipients` is a thunk so a peer roster change is picked up on the next submit without
+ * rebuilding the session.
+ */
+export function createBodyBuilder({ topic, encryption, multiDevice, }) {
+    const requestChannel = createRequestChannel(topic);
+    const responseChannel = createResponseChannel(topic);
+    const seal = (channel, payload) => payload.andThen(encryption.encrypt).map(data => ({ channel, topics: [topic], data }));
+    // Wrap an inner Request/Response into its multi-device StatementData variant.
+    const wrap = (md, inner, toStatementData) => inner
+        .andThen(bytes => md.envelope.wrap(bytes, md.recipients()))
+        .andThen(wrapped => encodeStatementData(toStatementData(wrapped.encryptedPayload, wrapped.devicesInfo)));
+    return {
+        buildRequest(requestId, messages) {
+            return seal(requestChannel, multiDevice
+                ? wrap(multiDevice, encodeRequest({ requestId, data: messages }), (encryptedRequest, devicesInfo) => ({
+                    tag: 'multiRequest',
+                    value: { encryptedRequest, devicesInfo },
+                }))
+                : encodeStatementData({ tag: 'request', value: { requestId, data: messages } }));
+        },
+        buildResponse(requestId, responseCode) {
+            return seal(responseChannel, multiDevice
+                ? wrap(multiDevice, encodeResponse({ requestId, responseCode }), (encryptedResponse, devicesInfo) => ({
+                    tag: 'multiResponse',
+                    value: { encryptedResponse, devicesInfo },
+                }))
+                : encodeStatementData({ tag: 'response', value: { requestId, responseCode } }));
+        },
+    };
+}

package/dist/session/core.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The session driver: turns the collaborators assembled by `createSession` /
+ * `createMultiDeviceSession` into a live {@link Session}.
+ *
+ * It never branches on single- vs multi-device. Wire format is decided by the injected
+ * {@link OutgoingBodyBuilder} and {@link StatementDecoder}; which topics to listen on by
+ * the injected {@link IncomingTopics}. Everything here is transport policy that both
+ * session kinds share: batching, dedup, the outgoing/incoming request state machine,
+ * expiry allocation, retries, and subscriber delivery.
+ */
+import type { StatementStoreAdapter } from '../adapter/types.js';
+import type { SessionId } from '../model/session.js';
+import type { ExpiryAllocator } from '../submit/allocator.js';
+import type { StatementDecoder } from './codec/decoder.js';
+import type { DeviceTarget } from './codec/envelope.js';
+import type { IncomingTopics } from './codec/incomingTopics.js';
+import type { OutgoingBodyBuilder } from './codec/outgoingBody.js';
+import type { StatementProver } from './statementProver.js';
+import type { Session } from './types.js';
+/**
+ * The Bulletin statement store caps a statement at roughly 500 KiB of total encoded size
+ * (proof + channel + topics + expiry + data); 2 KiB leaves margin for the non-data fields.
+ * `DataTooLargeError.available` is the chain's authoritative number if this ever drifts.
+ *
+ * This is deliberately the transport's real capacity rather than an application policy.
+ * A too-small budget degrades silently — messages queue instead of batching, with no
+ * error — whereas a too-large one fails loudly and recoverably with `DataTooLargeError`.
+ * Applications that want a tighter bound (Android's chat uses 100 KiB) should pass their
+ * own `maxRequestSize`; base-spec.md leaves the choice to the Application Layer.
+ */
+export declare const DEFAULT_MAX_REQUEST_SIZE: number;
+/**
+ * Fixed per-statement wire overhead reserved before sizing the request payload:
+ * topic (32) + channel (32) + expiry (8) + proof signature (64) + signer (32).
+ * Mirrors the Android/iOS sessions, which size message batches against
+ * `maxStatementSize - overhead` rather than the raw statement limit.
+ */
+export declare const STATEMENT_OVERHEAD: number;
+/**
+ * Collaborators the driver runs on. `createSession` / `createMultiDeviceSession` assemble
+ * these; the driver itself never branches on single- vs multi-device.
+ */
+export type SessionCoreParams = {
+    statementStore: StatementStoreAdapter;
+    prover: StatementProver;
+    allocator: ExpiryAllocator;
+    maxRequestSize: number;
+    /** Wire-format writer, and the session's size oracle. */
+    bodyBuilder: OutgoingBodyBuilder;
+    /** Topic(s) we listen on, with the keys to read each. */
+    incomingTopics: IncomingTopics;
+    decoder: StatementDecoder;
+    /** Topic our own statements are published on — queried to restore state at init. */
+    outgoingTopic: SessionId;
+    /** Peer devices, for reading back our own multi-device envelopes. Empty when single-device. */
+    peerDevices: () => DeviceTarget[];
+};
+export declare function createSessionCore({ statementStore, prover, allocator, maxRequestSize, bodyBuilder, incomingTopics, decoder, outgoingTopic, peerDevices, }: SessionCoreParams): Session;