feat: multi-device SSO V2 + chat V2

[kalininilya]

Summary

Brings multi-device SSO + V2 chat content to host-papp and host-chat. The public auth surface stays V1-shaped: createAuth / pappAdapter.sso keeps the pairingStatus / authenticate() / abortAuthentication() triad, authenticate() still resolves to a StoredUserSession | null, and pairingStatus.finished still carries session. What's new is the protocol underneath — pairing now runs the V2 multi-device handshake.

For a 0.7.8 consumer, the migration is two field renames (metadata URL → inline hostMetadata, osType/osVersion → platformType/platformVersion). Everything else is a drop-in upgrade.

Spec: https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/Ski9naYdWe

Desktop counterpart: paritytech/polkadot-desktop#489.

host-papp — the public surface

const adapter = createPappAdapter({
  appId,
  hostMetadata,                              // { hostName?, hostVersion?, hostIcon?, platformType?, platformVersion?, custom? }
  // optional overrides — most hosts skip these:
  // deviceIdentity: () => deviceIdentityService.loadOrCreate(),
  // onAuthSuccess:   async ({ session, identityChatPrivateKey }) => { /* extras */ },
});

const result = await adapter.sso.authenticate();   // ResultAsync<StoredUserSession | null, Error>
// or: subscribe to adapter.sso.pairingStatus and call abortAuthentication() to cancel

What the SDK now owns (was previously consumer-side or part of the original PR)

• Device identity persistence. The SDK creates and persists a fresh DeviceIdentityForPairing to the configured StorageAdapter on first run and reuses it on subsequent launches. Hosts that want a different backend (Electron Keychain, native secure storage) plug it in with an optional deviceIdentity: () => Promise<DeviceIdentityForPairing> factory.
• Pairing-topic statement dedupe. Stale Success statements on chain no longer get replayed across launches — the SDK persists the dedupe hex via the same StorageAdapter. No consumer plumbing.
• Internal persistence on Success. createAuth builds a V2-shaped StoredUserSession and writes it + per-session secrets to ssoSessionRepository and userSecretRepository. authenticate() resolves with the StoredUserSession; pairingStatus.finished.session carries the same object.
• Peer device statement account capture. Lifted off statement.proof.value.signer during pairing and exposed via session.remoteAccount.accountId (no follow-up chain query needed for device-sync seeding).

Consumer-facing changes vs 0.7.8

0.7.8	0.8.0
metadata: string (URL)	dropped — host name/icon/platform inline via hostMetadata
hostMetadata: { hostVersion, osType, osVersion }	reshape — { hostName?, hostVersion?, hostIcon?, platformType?, platformVersion?, custom? }
pairingStatus: { step, … }	unchanged (same step set, same shape)
authenticate(): ResultAsync<StoredUserSession | null, Error>	unchanged signature; the resolved StoredUserSession gains optional V2 fields (identityAccountId, identityChatPublicKey)
abortAuthentication()	unchanged
internal V1 sessions	wiped on first read via safe-decode-or-discard (V1 codec ≠ V2 codec)

Public exports

createPappAdapter / PappAdapter, AuthComponent / HostMetadata / OnAuthSuccess / PairingStatus / DeviceIdentityForPairing, UserSession / StoredUserSession / Identity, signing request/response types, RingVrf*, SS_*_ENDPOINTS.

V2 internals — startPairingV2, codecs (Handshake*, *HandshakeResponse*, VersionedHandshake*, MetadataEntry, MetadataKey, Device), the state-machine helpers, topic / envelope / proposal helpers, deriveIdentityChatPublicKey, the Handshake*State types — are all internal to the package.

host-papp — what changed under the hood

• V2 SSO inside createAuth — startPairingV2 is now called only from inside createAuth. The caller (or the SDK's default) provides a persistent DeviceIdentityForPairing; the SDK runs the full pairing dance (codec, ECDH envelope, polling fallback, state machine, peer-signer capture) and resolves authenticate() with the persisted StoredUserSession.
• HandshakeSuccessV2 wire — spec v0.2.1 161-byte shape: identityAccountId(32) || rootAccountId(32) || identityChatPrivateKey(32) || deviceEncPubKey(65). The 129-byte v0.2 variant emitted by Android feature/location-for-handshake is still accepted (with rootAccountId === null).
• Multi-device authorisation lives in the user-identity-signed roster events (DeviceAdded / DeviceRemoved); the success body has no per-device identitySignature.
• EncryptedHandshakeResponseV2 uses native scale-ts Enum on the inner discriminant. The peer SCALE library does NOT elide the inner index, so Pending(AllowanceAllocation) arrives as 0x00 0x00.
• HostMetadata reshape to mirror the V2 proposal — name / icon / platform now ride inside the QR proposal instead of being fetched from the V1 metadata: string URL (which is dropped).
• Schemas evolved + safe-decode-or-wipe. StoredUserSession gains optional V2 fields (identityAccountId, identityChatPublicKey). UserSecretRepository gains identityChatPrivateKey. Old V1 blobs decode short and are silently wiped on first read.
• identity/rpcAdapter tolerates camel/snake-case Resources.Consumers fields (fullUsername/full_username, lastUpdate/last_update, accountId/account_id) — the V2 multi-device runtime metadata emits camelCase.
• V1 handshake codec deleted — src/sso/auth/scale/handshake.ts is gone, along with the V1 ephemeral-keypair derivation in createAuth.

host-chat

• New MessageContent variants at the spec'd indices 14–20:
  • chatAccepted (14) — legacy single-device accept now carries { messageId } for iOS V1 backward decode (was _void).
  • _reserved16 (16), _reserved19 (19) — placeholders so subsequent indices land at the spec values.
  • deviceAdded (17) { statementAccountId, encryptionPublicKey }
  • deviceRemoved (18) { statementAccountId }
  • deviceChatAccepted (20) { requestId, device: DeviceInfo }. Sent on the identity-level session SessionId(B, A) encrypted with K(A,B) so all of A's devices can decrypt without a per-device envelope.
• DeviceAdded / DeviceRemoved use length-prefixed Bytes() rather than fixed-size codecs, because substrate-sdk-android falls through to length-prefixed Vec<u8> for the AccountId / EncodedPublicKey wrapper types (no @FixedLength).
• accountService.getConsumerInfo gets the same camel/snake-case tolerance as host-papp.

Backwards compatibility (vs. 0.7.8)

• V1 SSO is not supported. Paired Polkadot Mobile clients still on the V1 wire format will not pair against this build.
• V1 chat MessageContent variants 0–13 are preserved on the receive path, but chatAccepted (14) payload shape changed and older clients emitting _void will not decode.
• The transitional 129-byte V2 success body (Android feature/location-for-handshake) is still accepted.
• Persisted V1 SSO sessions and per-session secrets are wiped on first read (codec schema changed). Users will need to re-pair against a multi-device PApp build.

Test plan

• npm run build
• npm run typecheck
• npm run lint
• npm test — 524/524 (52 test files); auth.spec.ts covers V2-driven createAuth end-to-end (success path, internal persistence, onAuthSuccess hook, default deviceIdentity fallback, Failed inner response, abort, debug emits)
• Downstream consumer (polkadot-desktop, branch feat/multi-device-messaging-and-sync-rebased) typechecks, lints, builds, and unit tests pass against the linked SDK
• CI green
• Manual: pair against a multi-device PApp build through Onboarding

---

Release 0.8.0

(See CHANGELOG.md on this branch for the full entry. The summary below reflects the diff vs. 0.7.8, the last released version.)

What's new

• host-papp: multi-device SSO behind the existing createAuth / pappAdapter.sso surface. V2 wire format runs inside the SDK. authenticate() still resolves to StoredUserSession | null; pairingStatus.finished still carries session.
• host-papp: SDK persists the V2 device identity by default (overridable via deviceIdentity factory).
• host-papp: SDK persists pairing-topic statement dedupe internally; no consumer wiring.
• host-papp: StoredUserSession exposes the peer device statement account (via remoteAccount.accountId) and the user identity / chat keys (via identityAccountId / identityChatPublicKey).
• host-papp: optional onAuthSuccess hook for consumer post-pairing work (telemetry, custom peer caches).
• host-chat: new MessageContent variants at indices 14, 17, 18, 20 for multi-device chat.

Breaking (two field renames; nothing else)

• createPappAdapter drops metadata: string; host name / icon / platform now in hostMetadata.
• HostMetadata: osType → platformType, osVersion → platformVersion; add hostName? / hostIcon? / custom?.
• V1 SSO handshake removed; V1-only paired clients won't pair. Persisted V1 SSO sessions are wiped on first read.
• MessageContent.chatAccepted (14) payload changed from _void to { messageId: string }.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	verifiablejs@​1.2.0

View full report