@novasamatech/statement-store 0.6.13 → 0.6.15

package/README.md

@@ -1,11 +1,272 @@
 # @novasamatech/statement-store
 
-Statement store integration layer.
+Encrypted, signed messaging over a Polkadot statement store. Provides a session abstraction for sending and receiving typed request/response messages between two on-chain accounts.
 
 ## Overview
 
+The library wraps the raw statement-store RPC into a typed session with:
+
+- End-to-end AES-GCM encryption (ECDH shared secret via sr25519)
+- sr25519 proof generation and verification on every statement
+- Codec-based message serialization / deserialization
+- Request/response correlation with automatic response acknowledgement
+
 ## Installation
 
 ```shell
 npm install @novasamatech/statement-store --save -E
 ```
+
+## Usage
+
+```ts
+import {
+  createSession,
+  createLocalSessionAccount,
+  createRemoteSessionAccount,
+  createAccountId,
+  createSr25519Secret,
+  deriveSr25519PublicKey,
+  createSr25519Prover,
+  createEncryption,
+  createLazyClient,
+  createPapiStatementStoreAdapter,
+} from '@novasamatech/statement-store';
+import { str } from 'scale-ts';
+
+// 1. Derive local key pair from entropy
+const localSecret = createSr25519Secret(entropy, '//wallet');
+const localPublicKey = deriveSr25519PublicKey(localSecret);
+
+// 2. Build account descriptors
+const localAccount = createLocalSessionAccount(createAccountId(localPublicKey));
+const remoteAccount = createRemoteSessionAccount(
+  createAccountId(remotePublicKey),
+  remotePublicKey,
+);
+
+// 3. Wire up the chain adapter
+const client = createLazyClient(provider);
+const statementStore = createPapiStatementStoreAdapter(client);
+
+// 4. Create session dependencies
+const prover = createSr25519Prover(localSecret);
+const encryption = createEncryption(remoteAccount.publicKey);
+
+// 5. Open session
+const session = createSession({ localAccount, remoteAccount, statementStore, encryption, prover });
+
+// Send a typed request and wait for the remote acknowledgement
+const result = await session.request(str, 'hello');
+
+// Clean up
+session.dispose();
+client.disconnect();
+```
+
+## API
+
+### `createSession(params)`
+
+Creates a `Session` for bidirectional typed messaging between two accounts.
+
+```ts
+function createSession(params: SessionParams): Session
+```
+
+**`SessionParams`**
+
+| Property | Type | Description |
+|---|---|---|
+| `localAccount` | `LocalSessionAccount` | The local side of the session |
+| `remoteAccount` | `RemoteSessionAccount` | The remote side of the session |
+| `statementStore` | `StatementStoreAdapter` | Chain adapter for submitting/subscribing to statements |
+| `encryption` | `Encryption` | Encryption instance (use `createEncryption`) |
+| `prover` | `StatementProver` | Proof signer/verifier (use `createSr25519Prover`) |
+
+**`Session` methods**
+
+| Method | Signature | Description |
+|---|---|---|
+| `request` | `(codec, payload) → ResultAsync<void, Error>` | Submit a request and wait for the remote to acknowledge it. Resolves when the remote sends a success response; rejects on decoding/decryption failure or unknown error. |
+| `submitRequestMessage` | `(codec, payload) → ResultAsync<{ requestId }, Error>` | Submit a request without waiting for a response. Returns the generated `requestId`. |
+| `submitResponseMessage` | `(requestId, responseCode) → ResultAsync<void, Error>` | Send an explicit response to a request identified by `requestId`. |
+| `waitForRequestMessage` | `(codec, filter) → ResultAsync<S, Error>` | Wait for the next incoming request whose decoded payload passes `filter`. Unsubscribes automatically once matched. |
+| `waitForResponseMessage` | `(requestId) → ResultAsync<ResponseMessage, Error>` | Wait for the response to a specific outgoing request. |
+| `subscribe` | `(codec, callback) → VoidFunction` | Subscribe to all incoming messages, decoded with `codec`. Returns an unsubscribe function. |
+| `dispose` | `() → void` | Unsubscribe all active subscriptions created by this session. |
+
+---
+
+### Account factories
+
+#### `createAccountId(value)`
+
+Creates a 32-byte `AccountId` from a raw public key buffer.
+
+```ts
+function createAccountId(value: Uint8Array): AccountId
+```
+
+#### `createLocalSessionAccount(accountId, pin?)`
+
+Creates a `LocalSessionAccount` representing the local participant.
+
+```ts
+function createLocalSessionAccount(accountId: AccountId, pin?: string): LocalSessionAccount
+```
+
+`pin` is an optional string used to namespace the session channel.
+
+#### `createRemoteSessionAccount(accountId, publicKey, pin?)`
+
+Creates a `RemoteSessionAccount` representing the remote participant. `publicKey` is used for shared-secret derivation and session ID computation.
+
+```ts
+function createRemoteSessionAccount(
+  accountId: AccountId,
+  publicKey: Uint8Array,
+  pin?: string,
+): RemoteSessionAccount
+```
+
+#### `createSessionId(sharedSecret, accountA, accountB)`
+
+Derives a deterministic 32-byte session channel ID from a shared secret and two accounts.
+
+```ts
+function createSessionId(
+  sharedSecret: Uint8Array,
+  accountA: SessionAccount,
+  accountB: SessionAccount,
+): SessionId
+```
+
+---
+
+### Encryption
+
+#### `createEncryption(sharedSecret)`
+
+Creates an `Encryption` instance that encrypts/decrypts payloads with AES-256-GCM. The shared secret is typically the remote account's public key (ECDH result).
+
+```ts
+function createEncryption(sharedSecret: Uint8Array): Encryption
+```
+
+`Encryption` interface:
+
+| Method | Description |
+|---|---|
+| `encrypt(plaintext)` | Encrypts with a random 12-byte nonce prepended to the output |
+| `decrypt(ciphertext)` | Strips the nonce prefix and decrypts |
+
+---
+
+### Proof generation
+
+#### `createSr25519Prover(secret)`
+
+Creates a `StatementProver` that signs and verifies statement proofs using sr25519.
+
+```ts
+function createSr25519Prover(secret: Uint8Array): StatementProver
+```
+
+`StatementProver` interface:
+
+| Method | Description |
+|---|---|
+| `generateMessageProof(statement)` | Signs the statement and returns a `SignedStatement` |
+| `verifyMessageProof(statement)` | Verifies the sr25519 signature on an incoming statement |
+
+---
+
+### Chain adapter
+
+#### `createPapiStatementStoreAdapter(lazyClient)`
+
+Creates a `StatementStoreAdapter` backed by the polkadot-api JSON-RPC client.
+
+```ts
+function createPapiStatementStoreAdapter(lazyClient: LazyClient): StatementStoreAdapter
+```
+
+`StatementStoreAdapter` interface:
+
+| Method | Description |
+|---|---|
+| `queryStatements(topics, destination?)` | Fetch all current statements matching the given topics |
+| `subscribeStatements(topics, callback)` | Subscribe to new statements on topics; returns unsubscribe function |
+| `submitStatement(statement)` | Submit a signed statement; resolves on success, rejects with a typed error on failure |
+
+#### `createLazyClient(provider)`
+
+Creates a `LazyClient` that lazily initialises polkadot-api and substrate-client instances from a JSON-RPC provider.
+
+```ts
+function createLazyClient(provider: JsonRpcProvider): LazyClient
+```
+
+`LazyClient` methods:
+
+| Method | Description |
+|---|---|
+| `getClient()` | Returns (or creates) a `PolkadotClient` |
+| `getRequestFn()` | Returns a `RequestFn` for use with `sdk-statement` |
+| `getSubscribeFn()` | Returns a `SubscribeFn` for use with `sdk-statement` |
+| `disconnect()` | Destroys both underlying clients |
+
+---
+
+### Crypto utilities
+
+Low-level sr25519 helpers used to produce keys and proofs.
+
+#### `createSr25519Secret(entropy, derivation?)`
+
+Derives an sr25519 secret key from raw entropy, optionally applying a derivation path (`//hard` or `/soft` segments).
+
+```ts
+function createSr25519Secret(entropy: Uint8Array, derivation?: string): Uint8Array
+```
+
+#### `createSr25519Derivation(secret, derivation)`
+
+Applies a derivation path string to an existing sr25519 secret.
+
+```ts
+function createSr25519Derivation(secret: Uint8Array, derivation: string): Uint8Array
+```
+
+#### `deriveSr25519PublicKey(secret)`
+
+Derives the sr25519 public key from a secret key.
+
+```ts
+function deriveSr25519PublicKey(secret: Uint8Array): Uint8Array
+```
+
+#### `signWithSr25519Secret(secret, message)`
+
+Signs a message with an sr25519 secret key.
+
+```ts
+function signWithSr25519Secret(secret: Uint8Array, message: Uint8Array): Uint8Array
+```
+
+#### `verifySr25519Signature(message, signature, publicKey)`
+
+Verifies an sr25519 signature. Returns `true` if valid.
+
+```ts
+function verifySr25519Signature(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean
+```
+
+#### `khash(secret, message)`
+
+Computes a keyed blake2b-256 hash. Used internally to derive session channel IDs.
+
+```ts
+function khash(secret: Uint8Array, message: Uint8Array): Uint8Array
+```

package/dist/session/session.d.ts

@@ -9,5 +9,7 @@ export type SessionParams = {
     statementStore: StatementStoreAdapter;
     encryption: Encryption;
     prover: StatementProver;
+    maxRequestSize?: number;
 };
-export declare function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, }: SessionParams): Session;
+export declare function nextExpiry(current: bigint): bigint;
+export declare function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, maxRequestSize, }: SessionParams): Session;

package/dist/session/session.js

@@ -1,55 +1,246 @@
 import { createExpiryFromDuration } from '@novasamatech/sdk-statement';
 import { toHex } from '@polkadot-api/utils';
 import { nanoid } from 'nanoid';
-import { ResultAsync, err, fromPromise, fromThrowable, ok, okAsync } from 'neverthrow';
-import { Bytes } from 'scale-ts';
+import { ResultAsync, err, errAsync, fromPromise, fromThrowable, ok, okAsync } from 'neverthrow';
 import { khash, stringToBytes } from '../crypto.js';
 import { nonNullable, toError } from '../helpers.js';
 import { createSessionId } from '../model/session.js';
 import { DecodingError, DecryptionError, UnknownError } from './error.js';
 import { toMessage } from './messageMapper.js';
 import { StatementData } from './scale/statementData.js';
-export function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, }) {
-    let subscriptions = [];
-    function submit(sessionId, channel, data) {
+const DEFAULT_EXPIRY_DURATION_SECS = 7 * 24 * 60 * 60; // 7 days
+const DEFAULT_MAX_REQUEST_SIZE = 4096;
+export function nextExpiry(current) {
+    const fresh = createExpiryFromDuration(DEFAULT_EXPIRY_DURATION_SECS);
+    return fresh > current ? fresh : current + 1n;
+}
+export function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, maxRequestSize = DEFAULT_MAX_REQUEST_SIZE, }) {
+    const outgoingSessionId = createSessionId(remoteAccount.publicKey, localAccount, remoteAccount);
+    const incomingSessionId = createSessionId(remoteAccount.publicKey, remoteAccount, localAccount);
+    const state = {
+        phase: 'initialization',
+        expiry: 0n,
+        outgoingRequest: null,
+        incomingRequest: null,
+        respondedIncomingRequest: false,
+        messageQueue: [],
+        pendingDelivery: new Map(),
+        seenStatements: new Set(),
+    };
+    let subscribers = [];
+    const bufferedMessages = [];
+    let storeUnsub = null;
+    function submitStatementData(channel, topicSessionId, data) {
+        state.expiry = nextExpiry(state.expiry);
+        const expiry = state.expiry;
         return encryption
             .encrypt(data)
-            .map(data => ({
-            expiry: getExpiry(),
+            .map(encrypted => ({
+            expiry,
             channel: toHex(channel),
-            topics: [toHex(sessionId)],
-            data,
+            topics: [toHex(topicSessionId)],
+            data: encrypted,
         }))
             .asyncAndThen(prover.generateMessageProof)
             .andThen(statementStore.submitStatement);
     }
+    function encodeAndSubmitRequest(requestId, messages) {
+        const encode = fromThrowable(StatementData.enc, toError);
+        encode({ tag: 'request', value: { requestId, data: messages } })
+            .asyncAndThen(data => submitStatementData(createRequestChannel(outgoingSessionId), outgoingSessionId, data))
+            .mapErr(e => {
+            console.error('submitRequest failed:', e);
+        });
+    }
+    function deliverStatementData(statementData) {
+        if (subscribers.length === 0) {
+            if (state.phase === 'initialization') {
+                bufferedMessages.push(statementData);
+            }
+            return;
+        }
+        for (const sub of subscribers) {
+            const messages = toMessage(statementData, sub.codec);
+            if (messages.length > 0)
+                sub.callback(messages);
+        }
+    }
+    function tryDecodeStatement(statement) {
+        if (!statement.data)
+            return okAsync(null);
+        const data = statement.data;
+        return prover
+            .verifyMessageProof(statement)
+            .andThen(verified => (verified ? ok() : err(new Error('Invalid proof'))))
+            .andThen(() => encryption.decrypt(data))
+            .map(decrypted => StatementData.dec(decrypted))
+            .orElse(() => ok(null));
+    }
+    function processIncomingStatement(statement) {
+        if (!statement.data)
+            return;
+        const key = toHex(statement.data);
+        if (state.seenStatements.has(key))
+            return;
+        state.seenStatements.add(key);
+        tryDecodeStatement(statement).andTee(statementData => {
+            if (!statementData)
+                return;
+            if (statementData.tag === 'request') {
+                if (statementData.value.requestId === state.incomingRequest?.requestId)
+                    return;
+                state.incomingRequest = { requestId: statementData.value.requestId };
+                state.respondedIncomingRequest = false;
+                deliverStatementData(statementData);
+            }
+            else if (statementData.tag === 'response') {
+                if (state.outgoingRequest?.requestId !== statementData.value.requestId)
+                    return;
+                const responseMessage = {
+                    type: 'response',
+                    localId: statementData.value.requestId,
+                    requestId: statementData.value.requestId,
+                    responseCode: statementData.value.responseCode,
+                };
+                for (const token of state.outgoingRequest.tokens) {
+                    const deferred = state.pendingDelivery.get(token);
+                    if (deferred) {
+                        deferred.resolve(responseMessage);
+                        state.pendingDelivery.delete(token);
+                    }
+                }
+                state.outgoingRequest = null;
+                deliverStatementData(statementData);
+                processMessageQueue();
+            }
+        });
+    }
+    function processNewMessage(encoded, token) {
+        if (state.outgoingRequest === null) {
+            const requestId = nanoid();
+            state.outgoingRequest = { requestId, messages: [encoded], tokens: [token] };
+            encodeAndSubmitRequest(requestId, state.outgoingRequest.messages);
+        }
+        else {
+            const currentTotal = state.outgoingRequest.messages.reduce((s, m) => s + m.length, 0);
+            if (currentTotal + encoded.length <= maxRequestSize) {
+                state.outgoingRequest.messages.push(encoded);
+                state.outgoingRequest.tokens.push(token);
+                state.outgoingRequest.requestId = nanoid();
+                encodeAndSubmitRequest(state.outgoingRequest.requestId, state.outgoingRequest.messages);
+            }
+            else {
+                state.messageQueue.push({ encoded, token });
+            }
+        }
+    }
+    function processMessageQueue() {
+        const currentTotal = state.outgoingRequest?.messages.reduce((s, m) => s + m.length, 0) ?? 0;
+        while (state.messageQueue.length > 0) {
+            const head = state.messageQueue[0];
+            if (state.outgoingRequest !== null && currentTotal + head.encoded.length > maxRequestSize)
+                break;
+            state.messageQueue.shift();
+            processNewMessage(head.encoded, head.token);
+        }
+    }
+    function ensureStoreSubscription() {
+        if (storeUnsub)
+            return;
+        storeUnsub = statementStore.subscribeStatements([incomingSessionId], statements => {
+            for (const statement of statements) {
+                processIncomingStatement(statement);
+            }
+        });
+    }
+    async function init() {
+        const [ownResult, peerResult] = await Promise.all([
+            statementStore.queryStatements([outgoingSessionId]),
+            statementStore.queryStatements([incomingSessionId]),
+        ]);
+        if (ownResult.isErr() || peerResult.isErr())
+            return;
+        const ownStatements = ownResult.value;
+        const peerStatements = peerResult.value;
+        let maxExpiry = 0n;
+        for (const s of ownStatements) {
+            if (s.expiry !== undefined && s.expiry > maxExpiry)
+                maxExpiry = s.expiry;
+        }
+        state.expiry = nextExpiry(maxExpiry);
+        for (const s of [...ownStatements, ...peerStatements]) {
+            if (s.data)
+                state.seenStatements.add(toHex(s.data));
+        }
+        const decodeAll = (statements) => Promise.all(statements.map(s => tryDecodeStatement(s).match(v => v, () => null))).then(r => r.filter(nonNullable));
+        const [ownDecoded, peerDecoded] = await Promise.all([decodeAll(ownStatements), decodeAll(peerStatements)]);
+        const ownRequest = ownDecoded.find(d => d.tag === 'request');
+        const ownResponse = ownDecoded.find(d => d.tag === 'response');
+        const peerRequest = peerDecoded.find(d => d.tag === 'request');
+        const peerResponse = peerDecoded.find(d => d.tag === 'response');
+        if (ownRequest?.tag === 'request') {
+            const hasResponse = peerResponse?.tag === 'response' && peerResponse.value.requestId === ownRequest.value.requestId;
+            if (!hasResponse) {
+                state.outgoingRequest = {
+                    requestId: ownRequest.value.requestId,
+                    messages: ownRequest.value.data,
+                    tokens: [], // tokens from previous session cannot be restored
+                };
+            }
+        }
+        if (peerRequest?.tag === 'request') {
+            state.incomingRequest = { requestId: peerRequest.value.requestId };
+            state.respondedIncomingRequest =
+                ownResponse?.tag === 'response' && ownResponse.value.requestId === peerRequest.value.requestId;
+        }
+        // Notify app of any unresponded incoming request.
+        // Delivered while phase is still 'initialization' so that deliverStatementData
+        // buffers the message for replay if no subscriber is registered yet.
+        if (peerRequest && state.incomingRequest && !state.respondedIncomingRequest) {
+            deliverStatementData(peerRequest);
+        }
+        state.phase = 'active';
+        processMessageQueue();
+    }
     const session = {
         request(codec, data) {
-            return session.submitRequestMessage(codec, data).andThen(({ requestId }) => {
-                return session.waitForResponseMessage(requestId).andThen(({ responseCode }) => mapResponseCode(responseCode));
-            });
+            return session
+                .submitRequestMessage(codec, data)
+                .andThen(({ requestId }) => session.waitForResponseMessage(requestId).andThen(({ responseCode }) => mapResponseCode(responseCode)));
         },
         submitRequestMessage(codec, message) {
-            const requestId = nanoid();
-            const sessionId = createSessionId(remoteAccount.publicKey, localAccount, remoteAccount);
-            const encode = fromThrowable(StatementData.enc, toError);
-            const encoded = codec.enc(message);
-            const rawData = encode({
-                tag: 'request',
-                value: { requestId, data: [encoded] },
+            const encode = fromThrowable(codec.enc, toError);
+            const encodedResult = encode(message);
+            if (encodedResult.isErr())
+                return errAsync(encodedResult.error);
+            const encoded = encodedResult.value;
+            if (encoded.length > maxRequestSize)
+                return errAsync(new Error('message too big'));
+            const token = nanoid();
+            let resolveFn;
+            let rejectFn;
+            const promise = new Promise((res, rej) => {
+                resolveFn = res;
+                rejectFn = rej;
             });
-            return rawData
-                .asyncAndThen(data => submit(sessionId, createRequestChannel(sessionId), data))
-                .map(() => ({ requestId }));
+            state.pendingDelivery.set(token, { resolve: resolveFn, reject: rejectFn, promise });
+            if (state.phase === 'initialization') {
+                state.messageQueue.push({ encoded, token });
+            }
+            else {
+                processNewMessage(encoded, token);
+            }
+            return okAsync({ requestId: token });
         },
         submitResponseMessage(requestId, responseCode) {
-            const sessionId = createSessionId(remoteAccount.publicKey, localAccount, remoteAccount);
+            if (state.respondedIncomingRequest)
+                return okAsync(undefined);
+            if (state.incomingRequest?.requestId !== requestId) {
+                return errAsync(new Error(`No incoming request with id ${requestId}`));
+            }
+            state.respondedIncomingRequest = true;
             const encode = fromThrowable(StatementData.enc, toError);
-            const rawData = encode({
-                tag: 'response',
-                value: { requestId, responseCode },
-            });
-            return rawData.asyncAndThen(data => submit(sessionId, createResponseChannel(sessionId), data));
+            return encode({ tag: 'response', value: { requestId, responseCode } }).asyncAndThen(data => submitStatementData(createResponseChannel(incomingSessionId), incomingSessionId, data));
         },
         waitForRequestMessage(codec, filter) {
             const promise = new Promise(resolve => {
@@ -71,56 +262,47 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             });
             return fromPromise(promise, toError);
         },
-        waitForResponseMessage(requestId) {
-            const promise = new Promise(resolve => {
-                const unsub = session.subscribe(Bytes(), messages => {
-                    const response = messages.filter(m => m.type === 'response').find(m => m.requestId === requestId);
-                    if (response) {
-                        unsub();
-                        resolve(response);
-                    }
-                });
-            });
-            return fromPromise(promise, toError);
+        waitForResponseMessage(token) {
+            const deferred = state.pendingDelivery.get(token);
+            if (!deferred)
+                return errAsync(new Error(`No pending delivery for token ${token}`));
+            return fromPromise(deferred.promise, toError);
         },
         subscribe(codec, callback) {
-            const sessionId = createSessionId(remoteAccount.publicKey, remoteAccount, localAccount);
-            function processStatement(statement) {
-                if (!statement.data)
-                    return okAsync(null);
-                const data = statement.data;
-                return prover
-                    .verifyMessageProof(statement)
-                    .andThen(verified => (verified ? ok() : err(new Error('Statement proof is not valid'))))
-                    .andThen(() => encryption.decrypt(data))
-                    .map(StatementData.dec)
-                    .orElse(() => ok(null));
+            const sub = {
+                codec: codec,
+                callback: callback,
+            };
+            subscribers.push(sub);
+            ensureStoreSubscription();
+            // Deliver buffered init messages to this subscriber
+            if (bufferedMessages.length > 0) {
+                const messages = bufferedMessages.flatMap(sd => toMessage(sd, codec));
+                if (messages.length > 0)
+                    callback(messages);
             }
-            return statementStore.subscribeStatements([sessionId], statements => {
-                ResultAsync.combine(statements.map(processStatement))
-                    .map(messages => messages.filter(nonNullable).flatMap(x => toMessage(x, codec)))
-                    .andTee(messages => {
-                    if (messages.length > 0) {
-                        callback(messages);
-                    }
-                })
-                    // TODO rework
-                    .andTee(messages => {
-                    const requests = messages.filter(m => m.type === 'request').map(m => m.requestId);
-                    const responses = requests.map(requestId => session.submitResponseMessage(requestId, 'success'));
-                    return ResultAsync.combine(responses);
-                });
-            });
+            return () => {
+                subscribers = subscribers.filter(s => s !== sub);
+                if (subscribers.length === 0 && storeUnsub) {
+                    storeUnsub();
+                    storeUnsub = null;
+                }
+            };
         },
         dispose() {
-            for (const unsub of subscriptions) {
-                unsub();
+            storeUnsub?.();
+            storeUnsub = null;
+            subscribers = [];
+            for (const [, deferred] of state.pendingDelivery) {
+                deferred.reject(new Error('Session disposed'));
             }
-            subscriptions = [];
+            state.pendingDelivery.clear();
         },
     };
+    void init();
     return session;
 }
+// ── module-level helpers ──────────────────────────────────────────────────────
 function mapResponseCode(responseCode) {
     switch (responseCode) {
         case 'success':
@@ -133,10 +315,6 @@ function mapResponseCode(responseCode) {
             return err(new UnknownError());
     }
 }
-const DEFAULT_EXPIRY_DURATION_SECS = 7 * 24 * 60 * 60; // 7 days
-function getExpiry() {
-    return createExpiryFromDuration(DEFAULT_EXPIRY_DURATION_SECS);
-}
 function createRequestChannel(sessionId) {
     return khash(sessionId, stringToBytes('request'));
 }

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

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

package/dist/session/session.spec.js

@@ -0,0 +1,440 @@
+import { createExpiryFromDuration } from '@novasamatech/sdk-statement';
+import { ok, okAsync } from 'neverthrow';
+import { Bytes, str } from 'scale-ts';
+import { describe, expect, it, vi } from 'vitest';
+import { createAccountId, createLocalSessionAccount, createRemoteSessionAccount } from '../model/sessionAccount.js';
+import { StatementData } from './scale/statementData.js';
+import { createSession, nextExpiry } from './session.js';
+// ── test helpers ──────────────────────────────────────────────────────────────
+function makeAccounts() {
+    const localAccount = createLocalSessionAccount(createAccountId(new Uint8Array(32).fill(1)));
+    const remoteAccount = createRemoteSessionAccount(createAccountId(new Uint8Array(32).fill(2)), new Uint8Array(32).fill(3));
+    return { localAccount, remoteAccount };
+}
+function makeEncryption() {
+    return {
+        encrypt: (data) => ok(data),
+        decrypt: (data) => ok(data),
+    };
+}
+function makeProver() {
+    return {
+        generateMessageProof: s => okAsync({
+            ...s,
+            proof: {
+                type: 'sr25519',
+                value: {
+                    signature: `0x${'00'.repeat(64)}`,
+                    signer: `0x${'00'.repeat(32)}`,
+                },
+            },
+        }),
+        verifyMessageProof: () => okAsync(true),
+    };
+}
+function makeAdapter() {
+    const unsub = vi.fn();
+    return {
+        queryStatements: vi.fn().mockReturnValue(okAsync([])),
+        subscribeStatements: vi.fn().mockReturnValue(unsub),
+        submitStatement: vi.fn().mockReturnValue(okAsync(undefined)),
+    };
+}
+function makeStatement(statementData, expiry) {
+    return {
+        expiry: expiry ?? createExpiryFromDuration(7 * 24 * 60 * 60),
+        data: StatementData.enc(statementData),
+        topics: [],
+        channel: `0x${'00'.repeat(32)}`,
+    };
+}
+function makeSession(overrides) {
+    const { localAccount, remoteAccount } = makeAccounts();
+    const { maxRequestSize, ...adapterOverrides } = overrides ?? {};
+    const adapter = { ...makeAdapter(), ...adapterOverrides };
+    const session = createSession({
+        localAccount,
+        remoteAccount,
+        statementStore: adapter,
+        encryption: makeEncryption(),
+        prover: makeProver(),
+        maxRequestSize,
+    });
+    return { session, adapter };
+}
+async function flushPromises() {
+    await new Promise(resolve => setTimeout(resolve, 0));
+}
+describe('session', () => {
+    describe('nextExpiry', () => {
+        it('returns fresh expiry when current is 0', () => {
+            const result = nextExpiry(0n);
+            expect(result).toBeGreaterThan(0n);
+        });
+        it('returns fresh expiry when current is less than fresh', () => {
+            const stale = createExpiryFromDuration(1); // 1 second from now, will be smaller than 7-day
+            const result = nextExpiry(stale);
+            const fresh = createExpiryFromDuration(7 * 24 * 60 * 60);
+            expect(result).toBeGreaterThanOrEqual(fresh);
+        });
+        it('returns current + 1n when current is already at or above fresh', () => {
+            const high = createExpiryFromDuration(7 * 24 * 60 * 60 + 999999);
+            const result = nextExpiry(high);
+            expect(result).toBe(high + 1n);
+        });
+        it('is monotonically increasing across repeated calls', () => {
+            let expiry = 0n;
+            for (let i = 0; i < 5; i++) {
+                const next = nextExpiry(expiry);
+                expect(next).toBeGreaterThan(expiry);
+                expiry = next;
+            }
+        });
+    });
+    describe('createSession initialization', () => {
+        it('queries own and peer statements on creation', async () => {
+            const { adapter } = makeSession();
+            await flushPromises();
+            expect(adapter.queryStatements).toHaveBeenCalledTimes(2);
+        });
+        it('expiry is initialized from max own statement expiry', async () => {
+            const highExpiry = createExpiryFromDuration(7 * 24 * 60 * 60) + 9999n;
+            const ownRequest = makeStatement({ tag: 'request', value: { requestId: 'r1', data: [] } }, highExpiry);
+            const adapter = makeAdapter();
+            let firstCall = true;
+            adapter.queryStatements.mockImplementation(() => {
+                if (firstCall) {
+                    firstCall = false;
+                    return okAsync([ownRequest]);
+                }
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // Submit a message to trigger a statement — its expiry must be greater than highExpiry
+            const rawCodec = Bytes();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            await flushPromises();
+            const submittedStatement = adapter.submitStatement.mock.calls[0]?.[0];
+            if (submittedStatement) {
+                expect(submittedStatement.expiry).toBeGreaterThan(highExpiry);
+            }
+        });
+        it('marks own and peer statement data as seen during init', async () => {
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'r2', data: [new Uint8Array([1])] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // Register subscriber AFTER init — buffered incoming request should be delivered
+            const callback = vi.fn();
+            session.subscribe(Bytes(), callback);
+            expect(callback).toHaveBeenCalled();
+        });
+        it('transitions to active phase after queries complete', async () => {
+            const { session, adapter } = makeSession();
+            // Before init completes, submitRequestMessage queues the message
+            const rawCodec = str;
+            void session.submitRequestMessage(rawCodec, 'hello');
+            // Statement should NOT be submitted yet (still initializing)
+            expect(adapter.submitStatement).not.toHaveBeenCalled();
+            await flushPromises();
+            // After init, queued messages are processed → submitStatement called
+            expect(adapter.submitStatement).toHaveBeenCalled();
+        });
+    });
+    describe('session state restoration', () => {
+        it('restores outgoingRequest when own has request with no peer response', async () => {
+            const requestId = 'saved-request-id';
+            const ownRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 1)
+                    return okAsync([ownRequest]);
+                return okAsync([]); // no peer response
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // If outgoingRequest was restored, a new message appends to it
+            const codec = str;
+            void session.submitRequestMessage(codec, 'hello');
+            await flushPromises();
+            expect(adapter.submitStatement).toHaveBeenCalled();
+        });
+        it('clears outgoingRequest when peer has a matching response', async () => {
+            const requestId = 'acked-request';
+            const ownRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
+            const peerResponse = makeStatement({ tag: 'response', value: { requestId, responseCode: 'success' } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 1)
+                    return okAsync([ownRequest]);
+                return okAsync([peerResponse]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // No pending outgoing request — new message creates a brand new request
+            const codec = str;
+            void session.submitRequestMessage(codec, 'hi');
+            await flushPromises();
+            // submitStatement called exactly once (for the new message only)
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+        });
+        it('restores incomingRequest from peer statements', async () => {
+            const requestId = 'peer-request-id';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // Calling submitResponseMessage with restored requestId should succeed
+            const result = await session.submitResponseMessage(requestId, 'success');
+            expect(result.isOk()).toBe(true);
+        });
+        it('sets respondedIncomingRequest=true when own has a response for the peer request', async () => {
+            const requestId = 'peer-request-id';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
+            const ownResponse = makeStatement({ tag: 'response', value: { requestId, responseCode: 'success' } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 1)
+                    return okAsync([ownResponse]);
+                return okAsync([peerRequest]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            // Already responded — submitResponseMessage should return ok without submitting again
+            const submitsBefore = adapter.submitStatement.mock.calls.length;
+            const result = await session.submitResponseMessage(requestId, 'success');
+            expect(result.isOk()).toBe(true);
+            expect(adapter.submitStatement.mock.calls.length).toBe(submitsBefore); // no new submit
+        });
+    });
+    describe('subscribe', () => {
+        const rawCodec = Bytes();
+        it('delivers buffered init messages when subscriber registers after init', async () => {
+            const requestId = 'incoming-req';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1, 2, 3])] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises(); // init completes
+            const callback = vi.fn();
+            session.subscribe(rawCodec, callback);
+            expect(callback).toHaveBeenCalledTimes(1);
+            const messages = callback.mock.calls[0][0];
+            expect(messages[0]?.type).toBe('request');
+            expect(messages[0]?.requestId).toBe(requestId);
+        });
+        it('delivers init messages via subscribe when subscriber is registered before init completes', async () => {
+            const requestId = 'early-subscribe';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            const callback = vi.fn();
+            session.subscribe(rawCodec, callback); // before init completes
+            await flushPromises();
+            expect(callback).toHaveBeenCalledTimes(1);
+            const messages2 = callback.mock.calls[0][0];
+            expect(messages2[0]?.requestId).toBe(requestId);
+        });
+        it('does NOT deliver already-seen statements from subscription', async () => {
+            const requestId = 'seen-req';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
+            const adapter = makeAdapter();
+            let queryCallCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                queryCallCount++;
+                if (queryCallCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            let subscribeCallback;
+            adapter.subscribeStatements.mockImplementation((_topics, cb) => {
+                subscribeCallback = cb;
+                return vi.fn();
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises(); // init sees peerRequest, adds to seenStatements
+            const appCallback = vi.fn();
+            session.subscribe(rawCodec, appCallback);
+            // Simulate subscription delivering the same statement again
+            subscribeCallback([peerRequest]);
+            await flushPromises();
+            // Should only be called once (from buffered init message), not again from subscription
+            expect(appCallback).toHaveBeenCalledTimes(1);
+        });
+        it('does NOT auto-send a response when an incoming request arrives', async () => {
+            const requestId = 'no-auto-resp';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
+            const adapter = makeAdapter();
+            let subscribeCallback;
+            adapter.subscribeStatements.mockImplementation((_topics, cb) => {
+                subscribeCallback = cb;
+                return vi.fn();
+            });
+            adapter.queryStatements.mockReturnValue(okAsync([]));
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            const callback = vi.fn();
+            session.subscribe(rawCodec, callback);
+            adapter.submitStatement.mockClear();
+            subscribeCallback([peerRequest]);
+            await flushPromises();
+            // Message delivered to app callback but no automatic response submitted
+            expect(callback).toHaveBeenCalled();
+            expect(adapter.submitStatement).not.toHaveBeenCalled();
+        });
+        it('unsubscribing last subscriber tears down the store subscription', () => {
+            const { session, adapter } = makeSession();
+            const unsub = session.subscribe(rawCodec, vi.fn());
+            expect(adapter.subscribeStatements).toHaveBeenCalledTimes(1);
+            unsub();
+            // subscribeStatements returns a mock unsubscribe fn — verify it was called
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const storeMockUnsub = adapter.subscribeStatements.mock.results[0].value;
+            expect(storeMockUnsub).toHaveBeenCalled();
+        });
+    });
+    describe('submitResponseMessage', () => {
+        it('is idempotent — second call does not submit again', async () => {
+            const requestId = 'req-to-respond';
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
+            const adapter = makeAdapter();
+            let callCount = 0;
+            adapter.queryStatements.mockImplementation(() => {
+                callCount++;
+                if (callCount === 2)
+                    return okAsync([peerRequest]);
+                return okAsync([]);
+            });
+            const { session } = makeSession(adapter);
+            await flushPromises();
+            await session.submitResponseMessage(requestId, 'success');
+            const submitsAfterFirst = adapter.submitStatement.mock.calls.length;
+            await session.submitResponseMessage(requestId, 'success'); // second call
+            expect(adapter.submitStatement.mock.calls.length).toBe(submitsAfterFirst);
+        });
+        it('returns error when requestId does not match incomingRequest', async () => {
+            const { session } = makeSession();
+            await flushPromises();
+            const result = await session.submitResponseMessage('wrong-id', 'success');
+            expect(result.isErr()).toBe(true);
+        });
+    });
+    describe('message batching', () => {
+        const rawCodec = Bytes();
+        it('sends a single statement for the first message', async () => {
+            const { session, adapter } = makeSession();
+            await flushPromises();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            await flushPromises();
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+        });
+        it('appends second message to existing request (resubmits with new requestId)', async () => {
+            const { session, adapter } = makeSession();
+            await flushPromises();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([2]));
+            await flushPromises();
+            // Two submits: first for msg1, second for msg1+msg2 batched
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(2);
+        });
+        it('queues message that exceeds maxRequestSize', async () => {
+            const { session, adapter } = makeSession({ maxRequestSize: 5 });
+            await flushPromises();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3])); // 3 bytes — fits
+            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6, 7])); // 4 bytes — doesn't fit with existing
+            await flushPromises();
+            // Only first message sent; second is queued
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+        });
+        it('drains message queue after response received', async () => {
+            let subscribeCallback;
+            const subscribeStatements = vi
+                .fn()
+                .mockImplementation((_topics, cb) => {
+                subscribeCallback = cb;
+                return vi.fn();
+            });
+            const { session, adapter } = makeSession({ maxRequestSize: 5, subscribeStatements });
+            await flushPromises();
+            session.subscribe(Bytes(), vi.fn()); // ensure store subscription is active
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3])); // sent
+            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6])); // queued (doesn't fit)
+            await flushPromises();
+            const submitCountBefore = adapter.submitStatement.mock.calls.length;
+            // Simulate peer responding to the first request
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const lastSubmittedStatement = adapter.submitStatement.mock.calls[adapter.submitStatement.mock.calls.length - 1][0];
+            const decoded = StatementData.dec(lastSubmittedStatement.data);
+            const respondingRequestId = decoded.tag === 'request' ? decoded.value.requestId : '';
+            const responseStatement = makeStatement({
+                tag: 'response',
+                value: { requestId: respondingRequestId, responseCode: 'success' },
+            });
+            subscribeCallback([responseStatement]);
+            await flushPromises();
+            // Queued message should now be submitted
+            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThan(submitCountBefore);
+        });
+        it('waitForResponseMessage resolves when response arrives for batch', async () => {
+            let subscribeCallback;
+            const subscribeStatements = vi
+                .fn()
+                .mockImplementation((_topics, cb) => {
+                subscribeCallback = cb;
+                return vi.fn();
+            });
+            const { session, adapter } = makeSession({ subscribeStatements });
+            await flushPromises();
+            session.subscribe(Bytes(), vi.fn()); // ensure store subscription is active
+            const submitResult = await session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            const token = submitResult.unwrapOr({ requestId: '' }).requestId;
+            await flushPromises();
+            const responsePromise = session.waitForResponseMessage(token);
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const lastStatement = adapter.submitStatement.mock.calls[adapter.submitStatement.mock.calls.length - 1][0];
+            const decoded = StatementData.dec(lastStatement.data);
+            const respondingId = decoded.tag === 'request' ? decoded.value.requestId : '';
+            subscribeCallback([
+                makeStatement({ tag: 'response', value: { requestId: respondingId, responseCode: 'success' } }),
+            ]);
+            await flushPromises();
+            const result = await responsePromise;
+            expect(result.isOk()).toBe(true);
+            expect(result.unwrapOr({ responseCode: 'unknown' }).responseCode).toBe('success');
+        });
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/statement-store",
   "type": "module",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Statement store integration",
   "license": "Apache-2.0",
   "repository": {