@novasamatech/host-papp 0.7.9 → 0.8.0-1

package/README.md

@@ -60,7 +60,11 @@ const papp = createPappAdapter({
 Custom adapters (statement store, identity RPC, storage, lazy chain client) can be supplied
 via the `adapters` option for testing or non-browser environments.
 
-## Authentication and pairing
+## Authentication and pairing (V1)
+
+The V1 SSO flow described in this section is the single-device pairing protocol used by
+`papp.sso.authenticate()`. For the multi-device V2 protocol see
+[V2 SSO handshake](#v2-sso-handshake) below.
 
 `papp.sso.authenticate()` runs the full pairing + attestation flow and resolves with the
 stored user session, or `null` if the flow was aborted. The flow is idempotent — calling it
@@ -216,3 +220,168 @@ const lookup = async (accountId: string) => {
 // Batch lookup
 await papp.identity.getIdentities([accountIdA, accountIdB]);
 ```
+
+## V2 SSO handshake
+
+V2 is a redesign of the SSO pairing flow that supports the same user identity across
+multiple devices. The host generates a stable device keypair locally, emits a
+`VersionedHandshakeProposal::V2` via QR/deeplink, and an authorising peer (e.g. the user's
+existing Polkadot App) responds over the Statement Store with the user identity keys signed
+to authorise this device. Subsequent devices belonging to the same user reuse the same
+identity, so contacts, chats, and roster events are shared between them.
+
+V2 is **not interoperable with V1**: a V1-only peer can't decode a V2 proposal QR and vice
+versa. Hosts that want to support both should branch on which protocol the peer advertises.
+
+### Shape of the flow
+
+```
+host                                          peer (authorising device)
+────────────────────────────────────────────────────────────────────────
+buildPairingDeeplink(device, metadata)
+  →  polkadotapp://pair?handshake=<hex>
+                                              scan QR, decode proposal
+                                              compute pairing topic from
+                                              the host's pubkeys
+                                              ECDH-encrypt + post:
+                                                Pending(AllowanceAllocation)
+                                                Success { encryptionKey,
+                                                          accountId,
+                                                          identitySignature }
+                                                Failed(reason)
+service.subscribeStatements(topic) +
+  poll the topic every 2s
+  ↓
+decode VersionedHandshakeResponse::V2
+  → ECDH-decrypt envelope with the
+    device encryption private key
+  → SCALE-decode inner payload
+  → state machine: Submitted → Pending →
+    Success | Failed
+  → on Success persist user identity
+```
+
+The user identity carried in `Success` is the chat encryption pubkey + the user's identity
+sr25519 accountId. The host verifies the 64-byte sr25519 `identitySignature` against the
+canonical 97 bytes `statementAccountId || encryptionPublicKey`
+(see `IDENTITY_SIGNATURE_PAYLOAD_BYTES`).
+
+### Building and rendering the QR
+
+```ts
+import { buildPairingDeeplink } from '@novasamatech/host-papp';
+
+const deeplink = buildPairingDeeplink(
+  {
+    statementAccountPublicKey: device.statementAccountPublicKey, // sr25519 device pubkey, 32 bytes
+    encryptionPublicKey: device.encryptionPublicKey,             // P-256 device pubkey, 65 bytes uncompressed
+  },
+  {
+    hostName: 'My Host App',
+    hostVersion: '1.0.0',
+    platformType: 'macOS',
+    platformVersion: '15.4',
+  },
+);
+
+renderQrCode(deeplink); // 'polkadotapp://pair?handshake=<hex>'
+```
+
+### Driving the handshake
+
+```ts
+import { startPairingV2 } from '@novasamatech/host-papp';
+
+const pairing = startPairingV2({
+  statementStore: papp.adapters.statementStore, // any StatementStoreAdapter
+  deviceIdentity: {
+    statementAccountPublicKey: device.statementAccountPublicKey,
+    encryptionPublicKey: device.encryptionPublicKey,
+    encryptionPrivateKey: device.encryptionPrivateKey, // P-256 priv key, 32 bytes
+  },
+  metadata: {
+    hostName: 'My Host App',
+    hostVersion: '1.0.0',
+    platformType: 'macOS',
+    platformVersion: '15.4',
+  },
+  persistOnSuccess: async success => {
+    // success.identityChatPublicKey, success.userIdentityAccountId,
+    // success.identitySignature — persist in your secureStore.
+  },
+});
+
+pairing.qrPayload; // 'polkadotapp://pair?handshake=<hex>' for the QR UI
+
+pairing.state$.subscribe(state => {
+  switch (state.tag) {
+    case 'Submitted':
+      // QR shown, waiting for the peer to scan
+      return;
+    case 'Pending':
+      // peer acknowledged; allocating Statement Store allowance on-chain
+      return;
+    case 'Success':
+      // identity received, device authorised
+      return;
+    case 'Failed':
+      // peer rejected (declined / duplicate / no-slot / tx-failed)
+      console.error(state.reason);
+      return;
+  }
+});
+
+// Cancel mid-flight (the Observable completes, polling stops, subscription closes):
+pairing.abort();
+```
+
+### Surviving reloads / proper logout
+
+The chain holds the most recent statement on the pairing topic indefinitely, so on cold
+start the service will see the previous Success and replay it. To distinguish a stale
+replay from a fresh re-pair, callers can pass byte-level dedupe state:
+
+```ts
+const pairing = startPairingV2({
+  // ...
+  initialProcessedDataHex: await secureStore.get('lastProcessedHandshakeStatement'),
+  onStatementProcessed: hex => {
+    void secureStore.set('lastProcessedHandshakeStatement', hex);
+  },
+});
+```
+
+The service skips any incoming statement whose bytes match `initialProcessedDataHex`. PApp
+re-encrypts every Success with a fresh ephemeral key + AES-GCM nonce, so a genuine re-pair
+always produces different bytes and passes the dedupe.
+
+### Pairing topic / channel
+
+If the host needs to derive the pairing topic or channel itself (for example to subscribe
+in-line, or to verify a statement source):
+
+```ts
+import { computePairingTopic, computePairingChannel } from '@novasamatech/host-papp';
+
+const topic   = computePairingTopic(statementAccountId, encryptionPublicKey);
+const channel = computePairingChannel(statementAccountId, encryptionPublicKey);
+//   topic   = blake2b256_keyed(encryptionPublicKey || "topic",   key=statementAccountId)
+//   channel = blake2b256_keyed(encryptionPublicKey || "channel", key=statementAccountId)
+```
+
+### Codec exports
+
+The SCALE codecs are exported as plain `Codec<T>` values for callers that need to
+encode/decode statements outside the orchestrator:
+
+| Export                            | Description                                                                                  |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `VersionedHandshakeProposal`      | Outer enum; V2 at SCALE discriminant 1, with `_v1Reserved` at 0.                             |
+| `HandshakeProposalV2`             | `{ device, metadata }` — what the QR encodes.                                                |
+| `Device`                          | `{ statementAccountId(32), encryptionPublicKey(65) }`.                                        |
+| `MetadataKey`, `MetadataEntry`    | Metadata enum + `(MetadataKey, str)` tuple.                                                   |
+| `VersionedHandshakeResponse`      | Outer enum for the answer; `V1` legacy + `V2`.                                                |
+| `HandshakeResponseV2`             | `{ encrypted, tmpKey(65) }` — the ECDH-wrapped envelope.                                      |
+| `EncryptedHandshakeResponseV2`    | Inner payload after envelope decrypt: `Pending` (1 byte), `Success` (161 bytes), `Failed`.    |
+| `HandshakeSuccessV2`              | `{ encryptionKey(65), accountId(32), identitySignature(64) }`.                                |
+| `IDENTITY_SIGNATURE_PAYLOAD_BYTES`| `97` — the bytes the user identity sr25519 signs over.                                       |

package/dist/debugTypes.d.ts

@@ -25,7 +25,7 @@ export type SsoDebugEvent = {
     flowId: string;
     timestamp: number;
     payload: {
-        metadata: string;
+        metadata: unknown;
     };
 } | {
     layer: 'sso';
@@ -40,16 +40,14 @@ export type SsoDebugEvent = {
     event: 'awaiting_response';
     flowId: string;
     timestamp: number;
-    payload: {
-        topic: string;
-    };
+    payload: Record<string, never>;
 } | {
     layer: 'sso';
     event: 'response_received';
     flowId: string;
     timestamp: number;
     payload: {
-        sessionId: string;
+        identityAccountId: Uint8Array;
     };
 } | {
     layer: 'sso';

package/dist/identity/rpcAdapter.js

@@ -18,10 +18,16 @@ export function createIdentityRpcAdapter(lazyClient) {
                 if (!results) {
                     return ok({});
                 }
-                return ok(Object.fromEntries(zipWith([accounts, results], x => x).map(([accountId, raw]) => {
-                    if (!raw) {
+                return ok(Object.fromEntries(zipWith([accounts, results], x => x).map(([accountId, typedRaw]) => {
+                    if (!typedRaw) {
                         return [accountId, null];
                     }
+                    // Runtime metadata may expose fields in snake_case (V1) or
+                    // camelCase (V2 multi-device). Read defensively. The .papi
+                    // descriptor only types snake_case, so widen here.
+                    const raw = typedRaw;
+                    const fullUsername = raw.full_username ?? raw.fullUsername;
+                    const liteUsername = raw.lite_username ?? raw.liteUsername;
                     const credibility = raw.credibility.type == 'Lite'
                         ? {
                             type: 'Lite',
@@ -29,14 +35,15 @@ export function createIdentityRpcAdapter(lazyClient) {
                         : {
                             type: 'Person',
                             alias: raw.credibility.value.alias,
-                            lastUpdate: raw.credibility.value.last_update.toString(),
+                            lastUpdate: (raw.credibility.value.last_update ??
+                                raw.credibility.value.lastUpdate).toString(),
                         };
                     return [
                         accountId,
                         {
                             accountId: accountId,
-                            fullUsername: raw.full_username ? textDecoder.decode(raw.full_username) : null,
-                            liteUsername: textDecoder.decode(raw.lite_username),
+                            fullUsername: fullUsername ? textDecoder.decode(fullUsername) : null,
+                            liteUsername: liteUsername ? textDecoder.decode(liteUsername) : '',
                             credibility,
                         },
                     ];

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_PREVIEW_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS } from './constants.js';
 export type { PappAdapter } from './papp.js';
 export { createPappAdapter } from './papp.js';
-export type { HostMetadata } from './sso/auth/impl.js';
+export type { AuthComponent, HostMetadata, OnAuthSuccess } from './sso/auth/impl.js';
 export type { PairingStatus } from './sso/auth/types.js';
+export type { DeviceIdentityForPairing } from './sso/auth/v2/service.js';
 export type { UserSession } from './sso/sessionManager/userSession.js';
 export type { StoredUserSession } from './sso/userSessionRepository.js';
 export type { Identity } from './identity/types.js';

package/dist/papp.d.ts

@@ -1,7 +1,8 @@
 import type { LazyClient, StatementStoreAdapter } from '@novasamatech/statement-store';
 import type { StorageAdapter } from '@novasamatech/storage-adapter';
 import type { IdentityAdapter, IdentityRepository } from './identity/types.js';
-import type { AuthComponent, HostMetadata } from './sso/auth/impl.js';
+import type { AuthComponent, HostMetadata, OnAuthSuccess } from './sso/auth/impl.js';
+import type { DeviceIdentityForPairing } from './sso/auth/v2/service.js';
 import type { SsoSessionManager } from './sso/sessionManager/impl.js';
 import type { UserSecretRepository } from './sso/userSecretRepository.js';
 export type PappAdapter = {
@@ -18,27 +19,31 @@ type Adapters = {
 };
 type Params = {
     /**
-     * Host app Id.
-     * CAUTION! This value should be stable.
+     * Host app Id. CAUTION! This value should be stable across launches — it
+     * seeds the storage prefix that backs every persisted SSO blob.
      */
     appId: string;
     /**
-     * URL for additional metadata that will be displayed during pairing process.
-     * Content of provided json shound be
-     * ```ts
-     * interface Metadata {
-     *   name: string;
-     *   icon: string; // url for icon. Icon should be a rasterized image with min size 256x256 px.
-     * }
-     * ```
+     * Host environment metadata embedded inside the V2 pairing proposal QR so
+     * the paired device can render a request screen with the host name / icon /
+     * platform. All fields are optional — absence must not break pairing.
      */
-    metadata: string;
+    hostMetadata?: HostMetadata;
     /**
-     * Optional host environment metadata for Sign-In confirmation screen.
-     * All fields are optional - absence must not break the pairing flow.
+     * Optional override for the device identity. Default: the SDK persists a
+     * fresh identity to the configured `StorageAdapter` on first run and reuses
+     * it on subsequent launches. Pass a factory only if you need a different
+     * persistence backend (Electron Keychain, native secure storage, etc.).
      */
-    hostMetadata?: HostMetadata;
+    deviceIdentity?: () => Promise<DeviceIdentityForPairing> | DeviceIdentityForPairing;
+    /**
+     * Optional caller hook fired after a successful handshake — after the SDK
+     * has already written the session + secrets to its own repositories. Use it
+     * for consumer-specific bookkeeping (telemetry, custom peer caches, device-
+     * sync seeding). Throwing fails the `sso.authenticate()` call.
+     */
+    onAuthSuccess?: OnAuthSuccess;
     adapters?: Partial<Adapters>;
 };
-export declare function createPappAdapter({ appId, metadata, hostMetadata, adapters }: Params): PappAdapter;
+export declare function createPappAdapter({ appId, hostMetadata, deviceIdentity, onAuthSuccess, adapters, }: Params): PappAdapter;
 export {};

package/dist/papp.js

@@ -5,10 +5,11 @@ import { SS_STABLE_STAGE_ENDPOINTS } from './constants.js';
 import { createIdentityRepository } from './identity/impl.js';
 import { createIdentityRpcAdapter } from './identity/rpcAdapter.js';
 import { createAuth } from './sso/auth/impl.js';
+import { createDeviceIdentityStore } from './sso/deviceIdentityStore.js';
 import { createSsoSessionManager } from './sso/sessionManager/impl.js';
 import { createUserSecretRepository } from './sso/userSecretRepository.js';
 import { createUserSessionRepository } from './sso/userSessionRepository.js';
-export function createPappAdapter({ appId, metadata, hostMetadata, adapters }) {
+export function createPappAdapter({ appId, hostMetadata, deviceIdentity, onAuthSuccess, adapters, }) {
     const lazyClient = adapters?.lazyClient ??
         createLazyClient(getWsProvider(SS_STABLE_STAGE_ENDPOINTS, { heartbeatTimeout: Number.POSITIVE_INFINITY }));
     const statementStore = adapters?.statementStore ?? createPapiStatementStoreAdapter(lazyClient);
@@ -16,13 +17,16 @@ export function createPappAdapter({ appId, metadata, hostMetadata, adapters }) {
     const storage = adapters?.storage ?? createLocalStorageAdapter(appId);
     const ssoSessionRepository = createUserSessionRepository(storage);
     const userSecretRepository = createUserSecretRepository(appId, storage);
+    const deviceIdentityStore = createDeviceIdentityStore(appId, storage);
     return {
         sso: createAuth({
-            metadata,
             hostMetadata,
+            deviceIdentity,
+            deviceIdentityStore,
             statementStore,
             ssoSessionRepository,
             userSecretRepository,
+            onAuthSuccess,
         }),
         sessions: createSsoSessionManager({ storage, statementStore, ssoSessionRepository, userSecretRepository }),
         secrets: userSecretRepository,

package/dist/sso/auth/impl.d.ts

@@ -1,21 +1,39 @@
 import type { StatementStoreAdapter } from '@novasamatech/statement-store';
 import { ResultAsync } from 'neverthrow';
+import type { DeviceIdentityStore } from '../deviceIdentityStore.js';
 import type { UserSecretRepository } from '../userSecretRepository.js';
 import type { StoredUserSession, UserSessionRepository } from '../userSessionRepository.js';
+import type { HandshakeMetadata } from './v2/proposal.js';
+import type { DeviceIdentityForPairing } from './v2/service.js';
+export type HostMetadata = HandshakeMetadata;
 export type AuthComponent = ReturnType<typeof createAuth>;
-export type HostMetadata = {
-    hostVersion?: string;
-    osType?: string;
-    osVersion?: string;
-};
+/**
+ * Optional caller hook fired once the V2 handshake reaches Success, after the
+ * SDK has persisted the session and secrets and before `authenticate()`
+ * resolves. Receives both the persisted `StoredUserSession` and the sensitive
+ * `identityChatPrivateKey` (which lives in `UserSecretRepository` and isn't
+ * surfaced on the session shape). Throwing fails the `authenticate()` call.
+ */
+export type OnAuthSuccess = (event: {
+    session: StoredUserSession;
+    identityChatPrivateKey: Uint8Array;
+}) => Promise<void> | void;
 type Params = {
-    metadata: string;
     hostMetadata?: HostMetadata;
+    /**
+     * Optional override for the device identity. If absent, the SDK uses an
+     * internal `deviceIdentityStore` backed by the host's `StorageAdapter` —
+     * fine for web hosts. Electron / native consumers can plug in a Keychain-
+     * backed identity by passing a factory that returns the same shape.
+     */
+    deviceIdentity?: () => Promise<DeviceIdentityForPairing> | DeviceIdentityForPairing;
+    deviceIdentityStore: DeviceIdentityStore;
     statementStore: StatementStoreAdapter;
     ssoSessionRepository: UserSessionRepository;
     userSecretRepository: UserSecretRepository;
+    onAuthSuccess?: OnAuthSuccess;
 };
-export declare function createAuth({ metadata, hostMetadata, statementStore, ssoSessionRepository, userSecretRepository, }: Params): {
+export declare function createAuth({ hostMetadata, deviceIdentity, deviceIdentityStore, statementStore, ssoSessionRepository, userSecretRepository, onAuthSuccess, }: Params): {
     pairingStatus: {
         read: () => {
             step: "none";