@novasamatech/host-papp 0.7.9 → 0.8.0-0

package/dist/sso/auth/scale/handshakeV2.js

@@ -0,0 +1,176 @@
+/**
+ * SCALE codecs for the V2 SSO handshake (multi-device shape).
+ *
+ * The host emits a `VersionedHandshakeProposal::V2` via QR carrying its
+ * `Device { statementAccountId, encryptionPublicKey }` and metadata. The
+ * authorising peer (PApp) responds over the Statement Store with a
+ * `VersionedHandshakeResponse`; its body is ECDH-encrypted to the host's
+ * encryption public key with the peer's ephemeral `tmpKey`. The inner payload
+ * after decrypt is `EncryptedHandshakeResponseV2 = Pending | Success | Failed`.
+ *
+ * `Success` carries:
+ *   - `identityAccountId`     — user identity sr25519 accountId (32 bytes).
+ *                               Adressing for chat / username lookup / session
+ *                               topic derivation.
+ *   - `rootAccountId`         — user root sr25519 accountId (32 bytes). Parent
+ *                               for soft-derivation of product accounts; PApp
+ *                               and host MUST derive identically so a dapp sees
+ *                               the same address on every device.
+ *   - `identityChatPrivateKey`— user identity chat P-256 private scalar (32 bytes),
+ *                               shared per the multi-device spec so this device
+ *                               can decrypt traffic addressed to the user identity
+ *   - `deviceEncPubKey`       — encryption public key of the PApp device (65 bytes,
+ *                               P-256 uncompressed). Tells the host which key to
+ *                               use when addressing chat envelopes back to the
+ *                               authorising PApp device.
+ *
+ * Total wire length of `Success` is 32 + 32 + 32 + 65 = 161 bytes. Transit security
+ * comes from the outer envelope's ECDH-AES wrap; no per-field signature is
+ * carried — multi-device authorisation is asserted by the user-identity-signed
+ * roster events (`DeviceAdded`/`DeviceRemoved`) published separately.
+ */
+import { p256 } from '@noble/curves/nist.js';
+import { Bytes, Enum, Struct, Tuple, Vector, _void, str } from 'scale-ts';
+const AccountIdCodec = Bytes(32);
+const PublicKeyCodec = Bytes(65);
+const PrivateKeyCodec = Bytes(32);
+// ── Proposal ────────────────────────────────────────────────────────────
+export const MetadataKey = Enum({
+    Custom: str,
+    HostName: _void,
+    HostVersion: _void,
+    HostIcon: _void,
+    PlatformType: _void,
+    PlatformVersion: _void,
+});
+export const MetadataEntry = Tuple(MetadataKey, str);
+export const Device = Struct({
+    statementAccountId: AccountIdCodec,
+    encryptionPublicKey: PublicKeyCodec,
+});
+export const HandshakeProposalV2 = Struct({
+    device: Device,
+    metadata: Vector(MetadataEntry),
+});
+/**
+ * V2 lives at SCALE discriminant 1; index 0 is reserved for legacy V1 which
+ * neither side emits. The `_v1Reserved` slot pushes V2 to discriminant 1.
+ */
+export const VersionedHandshakeProposal = Enum({
+    _v1Reserved: _void,
+    V2: HandshakeProposalV2,
+});
+// ── Response (V2) ───────────────────────────────────────────────────────
+/** 32 + 32 + 32 + 65 = 161 bytes (spec v0.2.1) */
+export const HandshakeSuccessV2 = Struct({
+    identityAccountId: AccountIdCodec,
+    rootAccountId: AccountIdCodec,
+    identityChatPrivateKey: PrivateKeyCodec,
+    deviceEncPubKey: PublicKeyCodec,
+});
+/** 32 + 32 + 65 = 129 bytes (spec v0.2 — Android `feature/location-for-handshake`) */
+export const HandshakeSuccessV2Legacy = Struct({
+    identityAccountId: AccountIdCodec,
+    identityChatPrivateKey: PrivateKeyCodec,
+    deviceEncPubKey: PublicKeyCodec,
+});
+/**
+ * Length-dispatched decoder for the inner `EncryptedHandshakeResponseV2`
+ * plaintext. v0.2 (Android) ships 129-byte Success bodies without
+ * `rootAccountId`; v0.2.1 ships 161-byte bodies with it. Surfaces
+ * `rootAccountId: null` for the legacy case — chat doesn't need it.
+ */
+export const decodeEncryptedHandshakeResponseV2 = (bytes) => {
+    if (bytes.length === 0)
+        throw new Error('EncryptedHandshakeResponseV2: empty plaintext');
+    const tag = bytes[0];
+    // `slice` not `subarray` — scale-ts decoders read from buffer byteOffset 0.
+    const body = bytes.slice(1);
+    if (tag === 0) {
+        if (body.length === 0)
+            throw new Error('EncryptedHandshakeResponseV2: Pending body empty');
+        return { tag: 'Pending', value: { tag: 'AllowanceAllocation', value: undefined } };
+    }
+    if (tag === 1) {
+        if (body.length === 161) {
+            const decoded = HandshakeSuccessV2.dec(body);
+            return {
+                tag: 'Success',
+                value: {
+                    identityAccountId: decoded.identityAccountId,
+                    rootAccountId: decoded.rootAccountId,
+                    identityChatPrivateKey: decoded.identityChatPrivateKey,
+                    deviceEncPubKey: decoded.deviceEncPubKey,
+                },
+            };
+        }
+        if (body.length === 129) {
+            const decoded = HandshakeSuccessV2Legacy.dec(body);
+            return {
+                tag: 'Success',
+                value: {
+                    identityAccountId: decoded.identityAccountId,
+                    rootAccountId: null,
+                    identityChatPrivateKey: decoded.identityChatPrivateKey,
+                    deviceEncPubKey: decoded.deviceEncPubKey,
+                },
+            };
+        }
+        throw new Error(`EncryptedHandshakeResponseV2: Success body length ${body.length} not in {129, 161}`);
+    }
+    if (tag === 2) {
+        return { tag: 'Failed', value: str.dec(body) };
+    }
+    throw new Error(`EncryptedHandshakeResponseV2: unknown variant tag ${tag}`);
+};
+/**
+ * Derive the user identity chat P-256 public key from the shared private
+ * scalar received in `HandshakeSuccessV2`. Both desktop and mobile must derive
+ * identically (uncompressed 65-byte form) so downstream session topics agree.
+ */
+export const deriveIdentityChatPublicKey = (privateKey) => p256.getPublicKey(privateKey, false);
+/**
+ * Inner Pending sub-statuses. Only `AllowanceAllocation` today.
+ *
+ * Encoded with its own SCALE discriminant byte — the peer's SCALE library does
+ * NOT elide enum-variant indices for sealed interfaces (verified on the wire:
+ * `Pending(AllowanceAllocation)` arrives as `0x00 0x00`). Both sides must keep
+ * the discriminant when encoding so dispatch agrees.
+ */
+export const HandshakeStatusV2 = Enum({
+    AllowanceAllocation: _void,
+});
+/**
+ * Inner handshake response variant. Wire shape (matches peer SCALE encoding):
+ *
+ *   - Pending → 0x00 || HandshakeStatusV2 (today: 0x00 for AllowanceAllocation), 2 bytes total
+ *   - Success → 0x01 || HandshakeSuccessV2 (161 bytes), 162 bytes total
+ *   - Failed  → 0x02 || SCALE-encoded UTF-8 reason string
+ *
+ * Earlier builds shipped a custom length-dispatched codec assuming elision —
+ * that assumption was wrong and produced false `Failed("")` reads on every
+ * `Pending` response. Native scale-ts `Enum` preserves the discriminant and
+ * matches the peer's wire format directly.
+ */
+export const EncryptedHandshakeResponseV2 = Enum({
+    Pending: HandshakeStatusV2,
+    Success: HandshakeSuccessV2,
+    Failed: str,
+});
+export const HandshakeResponseV2 = Struct({
+    encrypted: Bytes(),
+    tmpKey: PublicKeyCodec,
+});
+/** Legacy V1 response shape — decoded for backward compat, never emitted by the V2 path. */
+export const HandshakeResponseV1 = Struct({
+    encrypted: Bytes(),
+    tmpKey: PublicKeyCodec,
+});
+export const EncryptedHandshakeResponseV1 = Struct({
+    encryptionKey: PublicKeyCodec,
+    accountId: AccountIdCodec,
+});
+export const VersionedHandshakeResponse = Enum({
+    V1: HandshakeResponseV1,
+    V2: HandshakeResponseV2,
+});

package/dist/sso/auth/v2/envelope.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Decrypt the outer envelope of a `HandshakeResponseV2` statement payload.
+ *
+ * The answering side generates a one-shot P-256 keypair, performs ECDH against
+ * the host device's encryption public key, and AES-GCM encrypts the sensitive
+ * payload (the SCALE-encoded `EncryptedHandshakeResponseV2`) with a key
+ * derived from the shared secret.
+ *
+ * The shared-secret-to-AES-key derivation (HKDF-SHA256 over the ECDH X
+ * coordinate) is delegated to `createEncryption(sharedSecret)` from
+ * `@novasamatech/statement-store` — byte-compatible with the existing V1
+ * chat-request encryption helper, so we don't fork primitives here.
+ */
+export type HandshakeResponseEnvelope = {
+    encrypted: Uint8Array;
+    tmpKey: Uint8Array;
+};
+export declare const decryptResponseEnvelope: (deviceEncryptionPrivateKey: Uint8Array, envelope: HandshakeResponseEnvelope) => Uint8Array;

package/dist/sso/auth/v2/envelope.js

@@ -0,0 +1,23 @@
+/**
+ * Decrypt the outer envelope of a `HandshakeResponseV2` statement payload.
+ *
+ * The answering side generates a one-shot P-256 keypair, performs ECDH against
+ * the host device's encryption public key, and AES-GCM encrypts the sensitive
+ * payload (the SCALE-encoded `EncryptedHandshakeResponseV2`) with a key
+ * derived from the shared secret.
+ *
+ * The shared-secret-to-AES-key derivation (HKDF-SHA256 over the ECDH X
+ * coordinate) is delegated to `createEncryption(sharedSecret)` from
+ * `@novasamatech/statement-store` — byte-compatible with the existing V1
+ * chat-request encryption helper, so we don't fork primitives here.
+ */
+import { p256 } from '@noble/curves/nist.js';
+import { createEncryption } from '@novasamatech/statement-store';
+const ecdhX = (privateKey, peerPublicKey) => p256.getSharedSecret(privateKey, peerPublicKey).slice(1, 33);
+export const decryptResponseEnvelope = (deviceEncryptionPrivateKey, envelope) => {
+    const shared = ecdhX(deviceEncryptionPrivateKey, envelope.tmpKey);
+    const result = createEncryption(shared).decrypt(envelope.encrypted);
+    if (result.isErr())
+        throw result.error;
+    return result.value;
+};

package/dist/sso/auth/v2/proposal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build the V2 SSO pairing proposal that the host emits via QR / deeplink.
+ *
+ * The encoded proposal goes into the `handshake` query parameter of a
+ * `polkadotapp://pair?handshake=<hex>` deeplink. The peer scans the QR,
+ * SCALE-decodes the bytes back into a `VersionedHandshakeProposal`, posts an
+ * encrypted answer to the corresponding pairing topic, and the host's
+ * subscription picks it up.
+ */
+export type HandshakeProposalDevice = {
+    statementAccountPublicKey: Uint8Array;
+    encryptionPublicKey: Uint8Array;
+};
+export type HandshakeMetadata = {
+    hostName?: string;
+    hostVersion?: string;
+    hostIcon?: string;
+    platformType?: string;
+    platformVersion?: string;
+    custom?: Record<string, string>;
+};
+export declare const encodeProposal: (device: HandshakeProposalDevice, metadata: HandshakeMetadata) => Uint8Array;
+export declare const buildPairingDeeplink: (device: HandshakeProposalDevice, metadata: HandshakeMetadata) => string;

package/dist/sso/auth/v2/proposal.js

@@ -0,0 +1,43 @@
+/**
+ * Build the V2 SSO pairing proposal that the host emits via QR / deeplink.
+ *
+ * The encoded proposal goes into the `handshake` query parameter of a
+ * `polkadotapp://pair?handshake=<hex>` deeplink. The peer scans the QR,
+ * SCALE-decodes the bytes back into a `VersionedHandshakeProposal`, posts an
+ * encrypted answer to the corresponding pairing topic, and the host's
+ * subscription picks it up.
+ */
+import { enumValue } from '@novasamatech/scale';
+import { toHex } from 'polkadot-api/utils';
+import { VersionedHandshakeProposal } from '../scale/handshakeV2.js';
+const PAIRING_DEEPLINK_PREFIX = 'polkadotapp://pair?handshake=';
+const buildMetadataEntries = (metadata) => {
+    const entries = [];
+    if (metadata.hostName !== undefined)
+        entries.push([enumValue('HostName', undefined), metadata.hostName]);
+    if (metadata.hostVersion !== undefined)
+        entries.push([enumValue('HostVersion', undefined), metadata.hostVersion]);
+    if (metadata.hostIcon !== undefined)
+        entries.push([enumValue('HostIcon', undefined), metadata.hostIcon]);
+    if (metadata.platformType !== undefined)
+        entries.push([enumValue('PlatformType', undefined), metadata.platformType]);
+    if (metadata.platformVersion !== undefined) {
+        entries.push([enumValue('PlatformVersion', undefined), metadata.platformVersion]);
+    }
+    for (const [key, value] of Object.entries(metadata.custom ?? {})) {
+        entries.push([enumValue('Custom', key), value]);
+    }
+    return entries;
+};
+export const encodeProposal = (device, metadata) => VersionedHandshakeProposal.enc(enumValue('V2', {
+    device: {
+        statementAccountId: device.statementAccountPublicKey,
+        encryptionPublicKey: device.encryptionPublicKey,
+    },
+    metadata: buildMetadataEntries(metadata),
+}));
+export const buildPairingDeeplink = (device, metadata) => {
+    const bytes = encodeProposal(device, metadata);
+    const hex = toHex(bytes).replace(/^0x/, '');
+    return `${PAIRING_DEEPLINK_PREFIX}${hex}`;
+};

package/dist/sso/auth/v2/service.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Orchestrates a single V2 SSO pairing exchange.
+ *
+ * Wires the codec, envelope, topic, and state-machine pieces together:
+ *   1. Encode the device's `VersionedHandshakeProposal::V2` and build the
+ *      `polkadotapp://pair?handshake=<hex>` deeplink (consumed by the QR UI).
+ *   2. Compute the pairing topic from the device pubkeys and subscribe to the
+ *      Statement Store on it.
+ *   3. For each incoming statement: SCALE-decode `VersionedHandshakeResponse`,
+ *      pull out the `V2` envelope, ECDH-decrypt the inner payload using the
+ *      device's encryption private key, SCALE-decode `EncryptedHandshakeResponseV2`,
+ *      and feed the result through the state machine via `fromInnerResponse` +
+ *      `advance`.
+ *   4. On `Success`, invoke the caller-supplied `persistOnSuccess` and stop.
+ *
+ * The chain RPC subscription only delivers a statement once when it first
+ * appears on a topic; channel replacements (Pending → Success on the same
+ * channel) don't reliably get re-broadcast as new events. So the service also
+ * polls `queryStatements` every 2s alongside the live subscription. Polling
+ * stops on terminal state and on `abort()`.
+ *
+ * Returns an Observable of `HandshakeState` and an `abort()` for cleanup —
+ * higher layers drive a UI hook off this and update an onboarding screen.
+ */
+import type { StatementStoreAdapter } from '@novasamatech/statement-store';
+import type { Observable } from 'rxjs';
+import type { HandshakeMetadata } from './proposal.js';
+import type { HandshakeState, HandshakeSuccessState } from './state.js';
+export type DeviceIdentityForPairing = {
+    statementAccountPublicKey: Uint8Array;
+    /**
+     * sr25519 secret for the device statement account. `startPairingV2` itself
+     * doesn't sign anything, but the post-pairing `StoredUserSession` needs it
+     * so the V1 sessionManager prover can issue session statements.
+     */
+    statementAccountSecret: Uint8Array;
+    encryptionPublicKey: Uint8Array;
+    encryptionPrivateKey: Uint8Array;
+};
+export type StartPairingDeps = {
+    statementStore: StatementStoreAdapter;
+    deviceIdentity: DeviceIdentityForPairing;
+    metadata: HandshakeMetadata;
+    persistOnSuccess?: (success: HandshakeSuccessState) => Promise<void>;
+    /**
+     * Hex of a previously-processed statement. The service will skip statements
+     * whose bytes match this value, treating them as already-handled. Useful for
+     * surviving page reloads / logouts so a stale Success on chain doesn't get
+     * replayed before the user re-authenticates.
+     */
+    initialProcessedDataHex?: string | null;
+    /**
+     * Fires whenever the service starts processing a new statement (i.e. after
+     * the byte-level dedupe passes). Callers persist the hex so the next
+     * `initialProcessedDataHex` value is up to date.
+     */
+    onStatementProcessed?: (dataHex: string) => void;
+};
+export type Pairing = {
+    qrPayload: string;
+    state$: Observable<HandshakeState>;
+    abort: () => void;
+};
+export declare const startPairingV2: (deps: StartPairingDeps) => Pairing;

package/dist/sso/auth/v2/service.js

@@ -0,0 +1,184 @@
+/**
+ * Orchestrates a single V2 SSO pairing exchange.
+ *
+ * Wires the codec, envelope, topic, and state-machine pieces together:
+ *   1. Encode the device's `VersionedHandshakeProposal::V2` and build the
+ *      `polkadotapp://pair?handshake=<hex>` deeplink (consumed by the QR UI).
+ *   2. Compute the pairing topic from the device pubkeys and subscribe to the
+ *      Statement Store on it.
+ *   3. For each incoming statement: SCALE-decode `VersionedHandshakeResponse`,
+ *      pull out the `V2` envelope, ECDH-decrypt the inner payload using the
+ *      device's encryption private key, SCALE-decode `EncryptedHandshakeResponseV2`,
+ *      and feed the result through the state machine via `fromInnerResponse` +
+ *      `advance`.
+ *   4. On `Success`, invoke the caller-supplied `persistOnSuccess` and stop.
+ *
+ * The chain RPC subscription only delivers a statement once when it first
+ * appears on a topic; channel replacements (Pending → Success on the same
+ * channel) don't reliably get re-broadcast as new events. So the service also
+ * polls `queryStatements` every 2s alongside the live subscription. Polling
+ * stops on terminal state and on `abort()`.
+ *
+ * Returns an Observable of `HandshakeState` and an `abort()` for cleanup —
+ * higher layers drive a UI hook off this and update an onboarding screen.
+ */
+import { BehaviorSubject } from 'rxjs';
+import { VersionedHandshakeResponse, decodeEncryptedHandshakeResponseV2 } from '../scale/handshakeV2.js';
+import { decryptResponseEnvelope } from './envelope.js';
+import { buildPairingDeeplink } from './proposal.js';
+import { advance, fromInnerResponse, isTerminal, submitted } from './state.js';
+import { computePairingTopic } from './topic.js';
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const toHexFull = (bytes) => {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return `0x${out}`;
+};
+const fromHexString = (hex) => {
+    const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const out = new Uint8Array(stripped.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+};
+const extractStatementSigner = (statement) => {
+    const proof = statement.proof;
+    if (!proof)
+        return null;
+    if (proof.type !== 'sr25519' && proof.type !== 'ed25519')
+        return null;
+    try {
+        return fromHexString(proof.value.signer);
+    }
+    catch {
+        return null;
+    }
+};
+export const startPairingV2 = (deps) => {
+    const persistOnSuccess = deps.persistOnSuccess;
+    const qrPayload = buildPairingDeeplink({
+        statementAccountPublicKey: deps.deviceIdentity.statementAccountPublicKey,
+        encryptionPublicKey: deps.deviceIdentity.encryptionPublicKey,
+    }, deps.metadata);
+    const state$ = new BehaviorSubject(submitted());
+    const topic = computePairingTopic(deps.deviceIdentity.statementAccountPublicKey, deps.deviceIdentity.encryptionPublicKey);
+    let aborted = false;
+    let unsubscribe = null;
+    let pollHandle = null;
+    let lastProcessedDataHex = deps.initialProcessedDataHex ?? null;
+    const stopPolling = () => {
+        if (pollHandle === null)
+            return;
+        clearInterval(pollHandle);
+        pollHandle = null;
+    };
+    const log = (msg, extra) => {
+        if (extra === undefined)
+            console.info(`[sso-v2] ${msg}`);
+        else
+            console.info(`[sso-v2] ${msg}`, extra);
+    };
+    log(`subscribing to pairing topic ${toHexFull(topic)}`);
+    log(`device statementAccountId ${toHexFull(deps.deviceIdentity.statementAccountPublicKey)}`);
+    log(`device encryptionPublicKey ${toHexFull(deps.deviceIdentity.encryptionPublicKey)}`);
+    // One-shot probe: query the topic right away so we know whether any answer
+    // statement was already posted before our subscription connected.
+    void deps.statementStore.queryStatements({ matchAll: [topic] }).match(statements => log(`queryStatements probe: ${statements.length} statement(s)`), err => log('queryStatements probe failed', err));
+    const handleStatement = (statement) => {
+        if (aborted || isTerminal(state$.value))
+            return;
+        if (!statement.data)
+            return;
+        const dataHex = toHexFull(statement.data);
+        if (dataHex === lastProcessedDataHex)
+            return;
+        lastProcessedDataHex = dataHex;
+        deps.onStatementProcessed?.(dataHex);
+        log(`statement received, ${statement.data.length}-byte payload`);
+        let envelope;
+        try {
+            const decoded = VersionedHandshakeResponse.dec(statement.data);
+            if (decoded.tag !== 'V2') {
+                log(`response is not V2 (tag=${decoded.tag}) — dropping`);
+                return;
+            }
+            envelope = decoded.value;
+        }
+        catch (err) {
+            log('VersionedHandshakeResponse.dec threw — dropping', err);
+            return;
+        }
+        let innerBytes;
+        try {
+            innerBytes = decryptResponseEnvelope(deps.deviceIdentity.encryptionPrivateKey, envelope);
+        }
+        catch (err) {
+            log('outer envelope decrypt failed — wrong recipient or tampered', err);
+            return;
+        }
+        const peerStatementAccountId = extractStatementSigner(statement);
+        let next;
+        try {
+            next = fromInnerResponse(decodeEncryptedHandshakeResponseV2(innerBytes), peerStatementAccountId);
+        }
+        catch (err) {
+            log(`inner decode failed; innerBytes (${innerBytes.length}b) = ${toHexFull(innerBytes)}`, err);
+            return;
+        }
+        log(`decoded inner response, tag=${next.tag}`);
+        if (next.tag === 'Failed') {
+            log(`failure reason: "${next.reason}" (innerBytes ${innerBytes.length}b = ${toHexFull(innerBytes)})`);
+        }
+        const advanced = advance(state$.value, next);
+        if (advanced === state$.value) {
+            // Same-tag idempotence is the common case (every poll re-fetches the
+            // current statement); only log when a transition was actually rejected
+            // for protocol-state reasons (e.g. Success → Pending).
+            if (advanced.tag !== next.tag) {
+                log(`advance() rejected ${state$.value.tag} → ${next.tag} — dropping`);
+            }
+            return;
+        }
+        log(`state ${state$.value.tag} → ${advanced.tag}`);
+        state$.next(advanced);
+        if (advanced.tag === 'Success' && persistOnSuccess !== undefined) {
+            void persistOnSuccess(advanced).catch(err => {
+                console.warn('persistHandshakeSuccess failed', err);
+            });
+        }
+        if (isTerminal(advanced)) {
+            stopPolling();
+        }
+    };
+    unsubscribe = deps.statementStore.subscribeStatements({ matchAll: [topic] }, page => {
+        log(`subscription page: ${page.statements.length} statement(s), isComplete=${page.isComplete}`);
+        for (const stmt of page.statements)
+            handleStatement(stmt);
+    });
+    // Poll because the chain RPC subscription doesn't deliver channel
+    // replacements as new events. handleStatement dedupes on data bytes so
+    // re-fetching the same Pending tick after tick is silent.
+    pollHandle = setInterval(() => {
+        if (aborted || isTerminal(state$.value))
+            return;
+        deps.statementStore.queryStatements({ matchAll: [topic] }).match(statements => {
+            for (const stmt of statements)
+                handleStatement(stmt);
+        }, err => log('poll queryStatements failed', err));
+    }, DEFAULT_POLL_INTERVAL_MS);
+    return {
+        qrPayload,
+        state$: state$.asObservable(),
+        abort: () => {
+            if (aborted)
+                return;
+            aborted = true;
+            stopPolling();
+            unsubscribe?.();
+            unsubscribe = null;
+            state$.complete();
+        },
+    };
+};

package/dist/sso/auth/v2/state.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Handshake V2 state machine — the public-facing observable shape of an
+ * in-flight SSO pairing exchange.
+ *
+ * Maps directly onto the inner `EncryptedHandshakeResponseV2` enum:
+ *
+ *   Idle       — no proposal emitted yet
+ *   Submitted  — proposal QR shown, waiting for the first response statement
+ *   Pending    — peer acknowledged; allocating Statement Store allowance on-chain
+ *   Success    — final state; identity keys received, device authorised
+ *   Failed     — final state; peer rejected (declined / duplicate / no-slot / tx-failed)
+ *
+ * Transitions are unidirectional except for Failed → Idle (user retries).
+ * The state object is what UIs render and what the chat layer gates on
+ * before submitting any V2 statements.
+ */
+import type { DecodedHandshakeResponseV2 } from '../scale/handshakeV2.js';
+export type HandshakeIdleState = {
+    tag: 'Idle';
+};
+export type HandshakeSubmittedState = {
+    tag: 'Submitted';
+};
+export type HandshakePendingState = {
+    tag: 'Pending';
+    reason: 'AllowanceAllocation';
+};
+export type HandshakeSuccessState = {
+    tag: 'Success';
+    /** User identity sr25519 accountId (32 bytes). */
+    identityAccountId: Uint8Array;
+    /**
+     * User root sr25519 accountId (32 bytes) — the parent for soft-derivation
+     * of product accounts. Nullable: peers on spec v0.2 (Android
+     * `feature/location-for-handshake`) omit this field. Product-account
+     * derivation degrades gracefully when absent; chat does not use it.
+     */
+    rootAccountId: Uint8Array | null;
+    /**
+     * User identity chat P-256 private key (32 bytes raw scalar) shared by
+     * PApp with this device per the multi-device spec. Sensitive; persist in
+     * OS-keychain-backed secure storage and never forward.
+     */
+    identityChatPrivateKey: Uint8Array;
+    /**
+     * Derived locally from `identityChatPrivateKey` via P-256 scalar
+     * multiplication (uncompressed 65-byte form). Both sides MUST derive
+     * identically; downstream session topics depend on it.
+     */
+    identityChatPublicKey: Uint8Array;
+    /**
+     * Encryption public key of the authorising PApp device (65 bytes,
+     * P-256 uncompressed). Used by the host when addressing chat envelopes
+     * back to the authorising device.
+     */
+    deviceEncPubKey: Uint8Array;
+    /**
+     * The pairing-topic statement was signed by PApp's device statement
+     * account. `HandshakeSuccessV2` doesn't carry it in the encrypted body, so
+     * the pairing service lifts it off `statement.proof.value.signer` and
+     * attaches it here. `null` only when the statement arrived without a
+     * recognised proof type, in which case device-sync can't seed back to PApp.
+     */
+    peerStatementAccountId: Uint8Array | null;
+};
+export type HandshakeFailedState = {
+    tag: 'Failed';
+    reason: string;
+};
+export type HandshakeState = HandshakeIdleState | HandshakeSubmittedState | HandshakePendingState | HandshakeSuccessState | HandshakeFailedState;
+export declare const idle: () => HandshakeIdleState;
+export declare const submitted: () => HandshakeSubmittedState;
+/**
+ * Translate the length-dispatched-decoded `EncryptedHandshakeResponseV2` into
+ * the public state. Pure — no I/O. The caller decrypts the outer envelope and
+ * runs `decodeEncryptedHandshakeResponseV2` first.
+ */
+export declare const fromInnerResponse: (response: DecodedHandshakeResponseV2, peerStatementAccountId?: Uint8Array | null) => HandshakeState;
+/**
+ * Forward-only transition guard: rejects regressions like Success → Pending.
+ * Idempotent on same-tag transitions (returns current by reference) so callers
+ * can use `next === current` to detect "no change" without per-call equality.
+ */
+export declare const advance: (current: HandshakeState, next: HandshakeState) => HandshakeState;
+export declare const isTerminal: (state: HandshakeState) => state is HandshakeSuccessState | HandshakeFailedState;
+/**
+ * True only when the device is authorised to submit V2 statements. The
+ * chat-send path gates on this — V2 messages must wait for allowance.
+ */
+export declare const canSubmitV2Statements: (state: HandshakeState) => state is HandshakeSuccessState;