@novasamatech/host-papp 0.7.9-5 → 0.7.9-6

package/dist/debug-public.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lightweight public entry for the debug bus. Lives outside the main
+ * `index.ts` so consumers can import the debug surface without
+ * loading the attestation / session-manager modules, which pull in
+ * verifiablejs WASM that can't initialise in all environments.
+ */
+export { emitHostPappDebugMessage, hasHostPappDebugListeners, onHostPappDebugMessage } from './debugBus.js';
+export type { AttestationDebugEvent, HostPappDebugEvent, SessionDebugEvent, SsoDebugEvent } from './debugTypes.js';

package/dist/debug-public.js

@@ -0,0 +1,7 @@
+/**
+ * Lightweight public entry for the debug bus. Lives outside the main
+ * `index.ts` so consumers can import the debug surface without
+ * loading the attestation / session-manager modules, which pull in
+ * verifiablejs WASM that can't initialise in all environments.
+ */
+export { emitHostPappDebugMessage, hasHostPappDebugListeners, onHostPappDebugMessage } from './debugBus.js';

package/dist/debugBus.d.ts

@@ -0,0 +1,20 @@
+import type { HostPappDebugEvent } from './debugTypes.js';
+/** @internal For host-papp emitters. */
+export declare function emitHostPappDebugMessage(event: HostPappDebugEvent): void;
+/**
+ * @internal Lets call sites skip non-trivial payload construction
+ * when nobody is listening. Equivalent in spirit to the lazy
+ * subscribe pattern in host-api's transport-level hook.
+ */
+export declare function hasHostPappDebugListeners(): boolean;
+/**
+ * EXPERIMENTAL. Subscribe to every host-papp debug event across all
+ * adapters in the current process. Returns an unsubscribe function.
+ *
+ * Each listener is isolated: a throw inside one callback is logged
+ * to `console.error` and does not starve sibling subscribers — the
+ * same pattern host-api uses in its transport-level debug hook.
+ */
+export declare function onHostPappDebugMessage(callback: (event: HostPappDebugEvent) => void): VoidFunction;
+/** @internal Convenience for creating flow identifiers. */
+export declare function createFlowId(): string;

package/dist/debugBus.js

@@ -0,0 +1,61 @@
+import { createNanoEvents } from 'nanoevents';
+import { nanoid } from 'nanoid';
+/**
+ * EXPERIMENTAL. Module-level bus that aggregates debug events from
+ * every host-papp adapter created in this process. Mirrors the
+ * pattern used by `onHostApiDebugMessage` in
+ * `@novasamatech/host-container` so a single subscriber can observe
+ * pairing / attestation / session activity alongside TrUAPI traffic.
+ *
+ * Subscription is *lazy in spirit*: emit sites should call
+ * `hasHostPappDebugListeners()` before constructing payloads that
+ * are non-trivial to compute.
+ */
+const bus = createNanoEvents();
+let listenerCount = 0;
+/** @internal For host-papp emitters. */
+export function emitHostPappDebugMessage(event) {
+    if (listenerCount === 0)
+        return;
+    bus.emit('message', event);
+}
+/**
+ * @internal Lets call sites skip non-trivial payload construction
+ * when nobody is listening. Equivalent in spirit to the lazy
+ * subscribe pattern in host-api's transport-level hook.
+ */
+export function hasHostPappDebugListeners() {
+    return listenerCount > 0;
+}
+/**
+ * EXPERIMENTAL. Subscribe to every host-papp debug event across all
+ * adapters in the current process. Returns an unsubscribe function.
+ *
+ * Each listener is isolated: a throw inside one callback is logged
+ * to `console.error` and does not starve sibling subscribers — the
+ * same pattern host-api uses in its transport-level debug hook.
+ */
+export function onHostPappDebugMessage(callback) {
+    listenerCount++;
+    const safeCallback = (event) => {
+        try {
+            callback(event);
+        }
+        catch (e) {
+            console.error('host-papp debug listener threw', e);
+        }
+    };
+    const unsubscribe = bus.on('message', safeCallback);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        listenerCount = Math.max(0, listenerCount - 1);
+        unsubscribe();
+    };
+}
+/** @internal Convenience for creating flow identifiers. */
+export function createFlowId() {
+    return nanoid();
+}

package/dist/debugTypes.d.ts

@@ -0,0 +1,204 @@
+/**
+ * EXPERIMENTAL. Discriminated union of every host-papp debug event.
+ * The taxonomy is split into three "layers": SSO pairing, guest
+ * identity attestation, and post-pairing session activity. Every
+ * variant carries `{ layer, event, flowId, timestamp, payload }`.
+ *
+ * `flowId` correlates steps that belong to the same logical flow
+ * (e.g. one full pairing dance shares a flowId across all of its
+ * steps). Conventions per layer:
+ *   - `sso.*` and `attestation.*`: one fresh flowId per pairing /
+ *     attestation attempt, shared across all of its steps.
+ *   - `session.opened` / `session.terminated`: reuse `sessionId` as the
+ *     flowId so that a `(opened, terminated)` pair stays queryable.
+ *   - `session.peer_action_*` and `session.host_action_*`: use the
+ *     per-message `messageId` as flowId so that received→processed /
+ *     received→failed and sent→response→failed triples line up.
+ *
+ * Mark anything subscribed to this taxonomy as EXPERIMENTAL on the
+ * consumer side — events and payloads may evolve across minor
+ * versions.
+ */
+export type SsoDebugEvent = {
+    layer: 'sso';
+    event: 'pairing_started';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        metadata: string;
+    };
+} | {
+    layer: 'sso';
+    event: 'deeplink_generated';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        deeplink: string;
+    };
+} | {
+    layer: 'sso';
+    event: 'awaiting_response';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        topic: string;
+    };
+} | {
+    layer: 'sso';
+    event: 'response_received';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    layer: 'sso';
+    event: 'session_established';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    layer: 'sso';
+    event: 'pairing_failed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        reason: string;
+    };
+};
+export type AttestationDebugEvent = {
+    layer: 'attestation';
+    event: 'started';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        candidateAccountId: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'username_claimed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        username: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'allowance_granted';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        verifierAccountId: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'vrf_proof_generated';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        candidateAccountId: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'person_registered';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        username: string;
+        candidateAccountId: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'completed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        username: string;
+    };
+} | {
+    layer: 'attestation';
+    event: 'failed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        reason: string;
+    };
+};
+export type SessionDebugEvent = {
+    layer: 'session';
+    event: 'opened';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+    };
+} | {
+    layer: 'session';
+    event: 'peer_action_received';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+        actionKind: string;
+    };
+} | {
+    layer: 'session';
+    event: 'peer_action_processed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+    };
+} | {
+    layer: 'session';
+    event: 'peer_action_failed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+        reason: string;
+    };
+} | {
+    layer: 'session';
+    event: 'host_action_sent';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+        actionKind: string;
+    };
+} | {
+    layer: 'session';
+    event: 'host_action_response_received';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+    };
+} | {
+    layer: 'session';
+    event: 'host_action_failed';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+        messageId: string;
+        reason: string;
+    };
+} | {
+    layer: 'session';
+    event: 'terminated';
+    flowId: string;
+    timestamp: number;
+    payload: {
+        sessionId: string;
+    };
+};
+export type HostPappDebugEvent = SsoDebugEvent | AttestationDebugEvent | SessionDebugEvent;

package/dist/debugTypes.js

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

package/dist/sso/auth/impl.js

@@ -4,6 +4,7 @@ import { generateMnemonic } from '@polkadot-labs/hdkd-helpers';
 import { Result, ResultAsync, err, fromPromise, fromThrowable, ok } from 'neverthrow';
 import { mergeUint8, toHex } from 'polkadot-api/utils';
 import { createEncrSecret, createSharedSecret, deriveSr25519Account, getEncrPub, stringToBytes } from '../../crypto.js';
+import { createFlowId, emitHostPappDebugMessage } from '../../debugBus.js';
 import { AbortError } from '../../helpers/abortError.js';
 import { createState, readonly } from '../../helpers/state.js';
 import { toError } from '../../helpers/utils.js';
@@ -13,7 +14,7 @@ export function createAuth({ metadata, hostMetadata, statementStore, ssoSessionR
     const pairingStatus = createState({ step: 'none' });
     let authResult = null;
     let abort = null;
-    function handshake(account, signal) {
+    function handshake(account, signal, flowId) {
         const localAccount = createLocalSessionAccount(createAccountId(account.publicKey));
         pairingStatus.write({ step: 'initial' });
         const encrKeys = createEncrKeys(account.entropy);
@@ -24,9 +25,26 @@ export function createAuth({ metadata, hostMetadata, statementStore, ssoSessionR
             hostMetadata,
         }));
         const handshakeTopic = encrKeys.andThen(({ publicKey }) => createHandshakeTopic(localAccount, publicKey));
-        const dataPrepared = Result.combine([handshakePayload, handshakeTopic, encrKeys]).andTee(([payload]) => pairingStatus.write({ step: 'pairing', payload: createDeeplink(payload) }));
+        const dataPrepared = Result.combine([handshakePayload, handshakeTopic, encrKeys]).andTee(([payload]) => {
+            const deeplink = createDeeplink(payload);
+            pairingStatus.write({ step: 'pairing', payload: deeplink });
+            emitHostPappDebugMessage({
+                layer: 'sso',
+                event: 'deeplink_generated',
+                flowId,
+                timestamp: Date.now(),
+                payload: { deeplink },
+            });
+        });
         return dataPrepared
             .asyncAndThen(([, handshakeTopic, encrKeys]) => {
+            emitHostPappDebugMessage({
+                layer: 'sso',
+                event: 'awaiting_response',
+                flowId,
+                timestamp: Date.now(),
+                payload: { topic: toHex(handshakeTopic) },
+            });
             const pappResponse = waitForStatements(callback => statementStore.subscribeStatements({ matchAll: [handshakeTopic] }, page => callback(page.statements)), signal, (statements, resolve) => {
                 for (const statement of statements) {
                     if (!statement.data)
@@ -37,6 +55,13 @@ export function createAuth({ metadata, hostMetadata, statementStore, ssoSessionR
                         payload: statement.data,
                     }).unwrapOr(null);
                     if (session) {
+                        emitHostPappDebugMessage({
+                            layer: 'sso',
+                            event: 'response_received',
+                            flowId,
+                            timestamp: Date.now(),
+                            payload: { sessionId: session.id },
+                        });
                         resolve(session);
                         break;
                     }
@@ -69,7 +94,15 @@ export function createAuth({ metadata, hostMetadata, statementStore, ssoSessionR
             }
             abort = new AbortController();
             const account = deriveSr25519Account(generateMnemonic(), '//wallet//sso');
-            authResult = handshake(account, abort.signal)
+            const ssoFlowId = createFlowId();
+            emitHostPappDebugMessage({
+                layer: 'sso',
+                event: 'pairing_started',
+                flowId: ssoFlowId,
+                timestamp: Date.now(),
+                payload: { metadata },
+            });
+            authResult = handshake(account, abort.signal, ssoFlowId)
                 .andThen(({ session, secretsPayload }) => {
                 return userSecretRepository
                     .write(secretsPayload.id, {
@@ -79,14 +112,32 @@ export function createAuth({ metadata, hostMetadata, statementStore, ssoSessionR
                 })
                     .andThen(() => ssoSessionRepository.add(session))
                     .map(() => session);
+            })
+                .andTee(session => {
+                if (session) {
+                    emitHostPappDebugMessage({
+                        layer: 'sso',
+                        event: 'session_established',
+                        flowId: ssoFlowId,
+                        timestamp: Date.now(),
+                        payload: { sessionId: session.id },
+                    });
+                }
             })
                 .orElse(e => (e instanceof AbortError ? ok(null) : err(e)))
                 .andTee(() => {
                 abort = null;
             })
-                .orTee(() => {
+                .orTee(e => {
                 authResult = null;
                 abort = null;
+                emitHostPappDebugMessage({
+                    layer: 'sso',
+                    event: 'pairing_failed',
+                    flowId: ssoFlowId,
+                    timestamp: Date.now(),
+                    payload: { reason: e.message },
+                });
             });
             return authResult;
         },

package/dist/sso/sessionManager/impl.js

@@ -1,5 +1,6 @@
 import { createEncryption } from '@novasamatech/statement-store';
 import { okAsync } from 'neverthrow';
+import { emitHostPappDebugMessage } from '../../debugBus.js';
 import { createState } from '../../helpers/state.js';
 import { createSsoStatementProver } from '../ssoSessionProver.js';
 import { createUserSession } from './userSession.js';
@@ -23,6 +24,13 @@ export function createSsoSessionManager({ ssoSessionRepository, userSecretReposi
                 continue;
             const session = createSession(userSession, statementStore, storage, userSecretRepository);
             toAdd.add(session);
+            emitHostPappDebugMessage({
+                layer: 'session',
+                event: 'opened',
+                flowId: userSession.id,
+                timestamp: Date.now(),
+                payload: { sessionId: userSession.id },
+            });
             const unsubscribe = session.subscribe(message => {
                 switch (message.data.tag) {
                     case 'v1': {
@@ -38,6 +46,13 @@ export function createSsoSessionManager({ ssoSessionRepository, userSecretReposi
         }
         if (toRemove.size > 0) {
             for (const id of toRemove) {
+                emitHostPappDebugMessage({
+                    layer: 'session',
+                    event: 'terminated',
+                    flowId: id,
+                    timestamp: Date.now(),
+                    payload: { sessionId: id },
+                });
                 releaseSession(id);
                 activeSessions[id]?.dispose();
             }

package/dist/sso/sessionManager/userSession.js

@@ -4,6 +4,7 @@ import { createSession } from '@novasamatech/statement-store';
 import { fieldListView } from '@novasamatech/storage-adapter';
 import { nanoid } from 'nanoid';
 import { ResultAsync, err, ok, okAsync } from 'neverthrow';
+import { emitHostPappDebugMessage } from '../../debugBus.js';
 import { createAsyncTaskPool } from '../../helpers/createAsyncTaskPool.js';
 import { toError } from '../../helpers/utils.js';
 import { RemoteMessageCodec } from './scale/remoteMessage.js';
@@ -16,6 +17,51 @@ function withQueueTimeout(resultAsync, label) {
     const timeoutPromise = new Promise(resolve => setTimeout(() => resolve(err(new Error(`${label} timed out — queue freed`))), QUEUE_TASK_TIMEOUT_MS));
     return ResultAsync.fromPromise(Promise.race([resultAsync, timeoutPromise]), toError).andThen(r => r);
 }
+/**
+ * Derive a stable `actionKind` label from a remote-message envelope.
+ * Shape: `OuterTag` for flat variants, `OuterTag:InnerTag` for variants
+ * whose payload is itself an enum (currently just `SignRequest`).
+ * The receive side and the send side both go through here so debug
+ * consumers see the same shape regardless of direction.
+ */
+function actionKindFromMessageData(data) {
+    if (data.tag !== 'v1')
+        return data.tag;
+    const inner = data.value;
+    if (inner.tag === 'SignRequest')
+        return `SignRequest:${inner.value.tag}`;
+    return inner.tag;
+}
+function emitHostAction(messageId, actionKind, sessionId) {
+    emitHostPappDebugMessage({
+        layer: 'session',
+        event: 'host_action_sent',
+        flowId: messageId,
+        timestamp: Date.now(),
+        payload: { sessionId, messageId, actionKind },
+    });
+}
+function withHostActionTrace(result, messageId, sessionId) {
+    return result
+        .andTee(() => {
+        emitHostPappDebugMessage({
+            layer: 'session',
+            event: 'host_action_response_received',
+            flowId: messageId,
+            timestamp: Date.now(),
+            payload: { sessionId, messageId },
+        });
+    })
+        .orTee(error => {
+        emitHostPappDebugMessage({
+            layer: 'session',
+            event: 'host_action_failed',
+            flowId: messageId,
+            timestamp: Date.now(),
+            payload: { sessionId, messageId, reason: error.message },
+        });
+    });
+}
 export function createUserSession({ userSession, statementStore, encryption, storage, prover, }) {
     const requestQueue = createAsyncTaskPool({ poolSize: 1, retryCount: 0, retryDelay: 0 });
     const session = createSession({
@@ -39,10 +85,9 @@ export function createUserSession({ userSession, statementStore, encryption, sto
         signPayload(payload) {
             return requestQueue.call(() => {
                 const messageId = nanoid();
-                const request = session.request(RemoteMessageCodec, {
-                    messageId,
-                    data: enumValue('v1', enumValue('SignRequest', enumValue('Payload', payload))),
-                });
+                const data = enumValue('v1', enumValue('SignRequest', enumValue('Payload', payload)));
+                emitHostAction(messageId, actionKindFromMessageData(data), userSession.id);
+                const request = session.request(RemoteMessageCodec, { messageId, data });
                 const responseFilter = (message) => {
                     if (message.data.tag === 'v1' &&
                         message.data.value.tag === 'SignResponse' &&
@@ -60,16 +105,15 @@ export function createUserSession({ userSession, statementStore, encryption, sto
                         return err(new Error(message.value));
                     }
                 });
-                return withQueueTimeout(inner, 'signPayload');
+                return withHostActionTrace(withQueueTimeout(inner, 'signPayload'), messageId, userSession.id);
             });
         },
         signRaw(payload) {
             return requestQueue.call(() => {
                 const messageId = nanoid();
-                const request = session.request(RemoteMessageCodec, {
-                    messageId,
-                    data: enumValue('v1', enumValue('SignRequest', enumValue('Raw', payload))),
-                });
+                const data = enumValue('v1', enumValue('SignRequest', enumValue('Raw', payload)));
+                emitHostAction(messageId, actionKindFromMessageData(data), userSession.id);
+                const request = session.request(RemoteMessageCodec, { messageId, data });
                 const responseFilter = (message) => {
                     if (message.data.tag === 'v1' &&
                         message.data.value.tag === 'SignResponse' &&
@@ -87,7 +131,7 @@ export function createUserSession({ userSession, statementStore, encryption, sto
                         return err(new Error(message.value));
                     }
                 });
-                return withQueueTimeout(inner, 'signRaw');
+                return withHostActionTrace(withQueueTimeout(inner, 'signRaw'), messageId, userSession.id);
             });
         },
         createTransaction(payload) {
@@ -128,13 +172,12 @@ export function createUserSession({ userSession, statementStore, encryption, sto
         getRingVrfAlias(productAccountId, productId) {
             return requestQueue.call(() => {
                 const messageId = nanoid();
-                const request = session.request(RemoteMessageCodec, {
-                    messageId,
-                    data: enumValue('v1', enumValue('RingVrfAliasRequest', {
-                        productAccountId,
-                        productId,
-                    })),
-                });
+                const data = enumValue('v1', enumValue('RingVrfAliasRequest', {
+                    productAccountId,
+                    productId,
+                }));
+                emitHostAction(messageId, actionKindFromMessageData(data), userSession.id);
+                const request = session.request(RemoteMessageCodec, { messageId, data });
                 const responseFilter = (message) => {
                     if (message.data.tag === 'v1' &&
                         message.data.value.tag === 'RingVrfAliasResponse' &&
@@ -142,9 +185,9 @@ export function createUserSession({ userSession, statementStore, encryption, sto
                         return message.data.value.value.payload;
                     }
                 };
-                return request
+                return withHostActionTrace(request
                     .andThen(() => session.waitForRequestMessage(RemoteMessageCodec, responseFilter))
-                    .andThen(result => (result.success ? ok(result.value) : err(new Error(result.value))));
+                    .andThen(result => (result.success ? ok(result.value) : err(new Error(result.value)))), messageId, userSession.id);
             });
         },
         requestResourceAllocation(request) {
@@ -179,9 +222,36 @@ export function createUserSession({ userSession, statementStore, encryption, sto
                             if (isMessageProcessed) {
                                 return okAsync({ processed: false });
                             }
+                            const messageId = payload.value.messageId;
+                            const actionKind = actionKindFromMessageData(payload.value.data);
+                            emitHostPappDebugMessage({
+                                layer: 'session',
+                                event: 'peer_action_received',
+                                flowId: messageId,
+                                timestamp: Date.now(),
+                                payload: { sessionId: userSession.id, messageId, actionKind },
+                            });
                             return callback(payload.value)
+                                .andTee(processed => {
+                                if (processed) {
+                                    emitHostPappDebugMessage({
+                                        layer: 'session',
+                                        event: 'peer_action_processed',
+                                        flowId: messageId,
+                                        timestamp: Date.now(),
+                                        payload: { sessionId: userSession.id, messageId },
+                                    });
+                                }
+                            })
                                 .orTee(error => {
                                 console.error('Error while processing sso message:', error);
+                                emitHostPappDebugMessage({
+                                    layer: 'session',
+                                    event: 'peer_action_failed',
+                                    flowId: messageId,
+                                    timestamp: Date.now(),
+                                    payload: { sessionId: userSession.id, messageId, reason: error.message },
+                                });
                             })
                                 .orElse(() => okAsync(false))
                                 .map(processed => (processed ? { processed, message: payload.value } : { processed }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-papp",
   "type": "module",
-  "version": "0.7.9-5",
+  "version": "0.7.9-6",
   "description": "Polkadot app integration",
   "license": "Apache-2.0",
   "repository": {
@@ -18,6 +18,11 @@
       "#/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./debug": {
+      "#/source": "./src/debug-public.ts",
+      "types": "./dist/debug-public.d.ts",
+      "default": "./dist/debug-public.js"
     }
   },
   "files": [
@@ -29,10 +34,10 @@
     "@noble/ciphers": "2.2.0",
     "@noble/curves": "2.2.0",
     "@noble/hashes": "2.2.0",
-    "@novasamatech/host-api": "0.7.9-5",
-    "@novasamatech/scale": "0.7.9-5",
-    "@novasamatech/statement-store": "0.7.9-5",
-    "@novasamatech/storage-adapter": "0.7.9-5",
+    "@novasamatech/host-api": "0.7.9-6",
+    "@novasamatech/scale": "0.7.9-6",
+    "@novasamatech/statement-store": "0.7.9-6",
+    "@novasamatech/storage-adapter": "0.7.9-6",
     "@polkadot-labs/hdkd-helpers": "^0.0.30",
     "nanoevents": "9.1.0",
     "nanoid": "5.1.9",