@novasamatech/host-chat 0.9.1 → 0.9.2

package/README.md

@@ -4,15 +4,14 @@ Account lookup and chat-message codecs for host applications integrating with th
 
 ## Overview
 
-`@novasamatech/host-chat` exposes the read side of the chat domain: discovering Polkadot
-accounts by username and resolving their on-chain identity from `Resources.Consumers`. It
-also publishes the SCALE codecs used by the chat wire protocol (messages, attachments,
-local-message envelopes) so host applications can decode statements they receive over the
-statement store.
+`@novasamatech/host-chat` exposes the read side of the chat domain: discovering Polkadot accounts by username and
+resolving their on-chain identity from `Resources.Consumers`. It also publishes the SCALE codecs used by the chat wire
+protocol (messages, attachments, local-message envelopes) so host applications can decode statements they receive over
+the statement store.
 
-The package is UI-framework agnostic. The main entry point returns plain async functions
-backed by [`neverthrow`](https://github.com/supermacro/neverthrow) `ResultAsync`, and the
-codec exports are pure SCALE codecs with no runtime side effects.
+The package is UI-framework agnostic. The main entry point returns plain async functions backed by
+[`neverthrow`](https://github.com/supermacro/neverthrow) `ResultAsync`, and the codec exports are pure SCALE codecs with
+no runtime side effects.
 
 ## Installation
 
@@ -24,10 +23,18 @@ npm install @novasamatech/host-chat --save -E
 
 ```ts
 import { createAccountService } from '@novasamatech/host-chat';
+import { createIdentityRepository, createIdentityRpcAdapter } from '@novasamatech/host-papp';
+import { createLocalStorageAdapter } from '@novasamatech/storage-adapter';
 import { createLazyClient } from '@novasamatech/statement-store';
 
 const lazyClient = createLazyClient(/* chain provider */);
-const accounts = createAccountService('paseo-next-v2', lazyClient);
+const accounts = createAccountService({
+  identityEndpoint: 'https://identity-backend.example/',
+  identity: createIdentityRepository({
+    adapter: createIdentityRpcAdapter(lazyClient),
+    storage: createLocalStorageAdapter('my-host-app'),
+  }),
+});
 
 // Search the off-chain username index for accounts whose username starts with `alice`.
 const search = await accounts.search('alice', 'ASSIGNED');
@@ -41,43 +48,58 @@ if (search.isOk()) {
 const identity = await accounts.getConsumerInfo('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY');
 if (identity.isOk() && identity.value) {
   console.log(identity.value.fullUsername, identity.value.credibility);
+
+  // 32-byte X25519 chat encryption key as hex, or null for a keypair type
+  // this SDK does not implement.
+  console.log(identity.value.identifierKey);
 }
 ```
 
-### Networks
+## API
 
-`createAccountService` accepts one of:
+### `createAccountService({ identityEndpoint, identity })`
 
-| Network          | People chain endpoint                  |
-| ---------------- | -------------------------------------- |
-| `stable`         | Polkadot People                        |
-| `preview`        | Westend People                         |
-| `paseo-next`     | Paseo People (V1)                      |
-| `paseo-next-v2`  | Paseo People (V2 multi-device)         |
+- **`identityEndpoint`** — base URL of the off-chain identity backend that `search` queries. A trailing slash is
+  optional.
+- **`identity`** — an identity repository, typed `IdentitySource` (`Pick<IdentityRepository, 'getIdentity'>` from
+  `@novasamatech/host-papp`).
 
-Each network entry pins both the People chain WebSocket URL (used via `lazyClient`) and
-the off-chain identity-backend REST endpoint that `search` queries.
+The service takes a repository rather than a chain client, so a host that also runs `createPappAdapter` can pass
+`papp.identity` straight in and share one cache and one chain connection:
 
-## API
+```ts
+const papp = createPappAdapter({ appId: 'my-host-app' });
+const accounts = createAccountService({ identityEndpoint, identity: papp.identity });
+```
 
-### `createAccountService(network, lazyClient)`
+It also makes the service trivial to test — the whole dependency is one function:
+
+```ts
+const accounts = createAccountService({
+  identityEndpoint,
+  identity: { getIdentity: () => okAsync(null) },
+});
+```
 
 Returns an object with two methods:
 
-- **`search(query, status)`** — query the off-chain username index. `status` is
-  `'ASSIGNED' | 'PENDING'`. Resolves to a list of `{ candidateAccountId, username, status,
-  onchainData, createdAt, updatedAt }` rows.
+- **`search(query, status)`** — query the off-chain username index. `status` is `'ASSIGNED' | 'PENDING'`. Resolves to a
+  list of `{ candidateAccountId, username, status, onchainData, createdAt, updatedAt }` rows.
 - **`getConsumerInfo(address)`** — resolve a single SS58 address to an `Identity`
-  (`{ accountId, fullUsername, liteUsername, credibility }`) by reading
-  `Resources.Consumers` from the People chain. Returns `null` if the account has no
-  consumer entry. Tolerates both snake_case (V1) and camelCase (V2) runtime field names.
+  (`{ accountId, fullUsername, liteUsername, credibility, identifierKey }`) by reading `Resources.Consumers` from the
+  People chain. Returns `null` if the account has no consumer entry, and an `err` if `address` is not a valid SS58
+  address.
 
 Both methods return `ResultAsync<…, Error>`; call `.isOk()` / `.isErr()` to discriminate.
 
+`Identity` and `Credibility` are re-exported from `@novasamatech/host-papp`, which owns the `Resources.Consumers` reader
+this package delegates to — see its [identity lookups](../host-papp/README.md#identity-lookups) section. Note that
+`credibility.lastUpdate` is `string | null`: it is `null` when the chain record carries no readable timestamp.
+
 ## Codec subpath exports
 
-The chat wire codecs are exposed under explicit subpaths so they can be tree-shaken
-independently of the main entry point:
+The chat wire codecs are exposed under explicit subpaths so they can be tree-shaken independently of the main entry
+point:
 
 ```ts
 import {
@@ -89,14 +111,10 @@ import {
   DeviceRemovedContent,
 } from '@novasamatech/host-chat/codec/message';
 
-import {
-  FileMeta,
-  FileVariant,
-  P2PMixnetFile,
-} from '@novasamatech/host-chat/codec/attachment';
+import { FileMeta, FileVariant, P2PMixnetFile } from '@novasamatech/host-chat/codec/attachment';
 
 import type { ChatSession } from '@novasamatech/host-chat/session';
 ```
 
-These are byte-compatible with the Android / iOS Polkadot Mobile clients — modify with
-care, the indices are pinned by the protocol.
+These are byte-compatible with the Android / iOS Polkadot Mobile clients — modify with care, the indices are pinned by
+the protocol.

package/dist/accountService.d.ts

@@ -1,9 +1,12 @@
+import type { Identity, IdentityRepository } from '@novasamatech/host-papp';
 import type { HexString } from '@novasamatech/scale';
-import type { LazyClient } from '@novasamatech/statement-store';
 import type { ResultAsync } from 'neverthrow';
+export type { Credibility, Identity } from '@novasamatech/host-papp';
+export type IdentitySource = Pick<IdentityRepository, 'getIdentity'>;
 interface Config {
     identityEndpoint: string;
-    client: LazyClient;
+    /** Pass `papp.identity`, or build one with `createIdentityRepository({ adapter, storage })`. */
+    identity: IdentitySource;
 }
 type AccountStatus = 'ASSIGNED' | 'PENDING';
 type AccountService = {
@@ -23,18 +26,4 @@ type SearchResponse = {
     createdAt: string;
     updatedAt: string;
 }[];
-export type Credibility = {
-    type: 'Lite';
-} | {
-    type: 'Person';
-    alias: `0x${string}`;
-    lastUpdate: string;
-};
-export type Identity = {
-    accountId: string;
-    fullUsername: string | null;
-    liteUsername: string;
-    credibility: Credibility;
-};
 export declare const createAccountService: (config: Config) => AccountService;
-export {};

package/dist/accountService.js

@@ -1,11 +1,14 @@
 import { toHex } from '@novasamatech/scale';
-import { AccountId } from '@polkadot-api/substrate-bindings';
-import { errAsync, fromPromise } from 'neverthrow';
+import { Result, errAsync, fromPromise } from 'neverthrow';
+import { AccountId } from 'polkadot-api';
 import { toError } from './helpers.js';
 export const createAccountService = (config) => {
     const identityEndpoint = config.identityEndpoint.endsWith('/')
         ? config.identityEndpoint
         : `${config.identityEndpoint}/`;
+    const accountIdCodec = AccountId();
+    // `enc` throws on a malformed SS58 address; keep that inside the Result.
+    const encodeAccountId = Result.fromThrowable((address) => toHex(accountIdCodec.enc(address)), toError);
     return {
         search(query, status) {
             // Build query string
@@ -25,36 +28,7 @@ export const createAccountService = (config) => {
             });
         },
         getConsumerInfo(address) {
-            const textDecoder = new TextDecoder();
-            const accountId = AccountId();
-            const client = config.client.getClient();
-            const api = client.getUnsafeApi();
-            const consumerInfo = fromPromise(api.query.Resources?.Consumers?.getValue(address), toError);
-            return consumerInfo.map(typedRaw => {
-                if (!typedRaw)
-                    return null;
-                // Runtime metadata may expose fields in snake_case (V1) or
-                // camelCase (V2 multi-device). Read defensively.
-                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',
-                    }
-                    : {
-                        type: 'Person',
-                        alias: raw.credibility.value.alias,
-                        lastUpdate: (raw.credibility.value.last_update ??
-                            raw.credibility.value.lastUpdate).toString(),
-                    };
-                return {
-                    accountId: toHex(accountId.enc(address)),
-                    fullUsername: fullUsername ? textDecoder.decode(fullUsername) : null,
-                    liteUsername: liteUsername ? textDecoder.decode(liteUsername) : '',
-                    credibility: credibility,
-                };
-            });
+            return encodeAccountId(address).asyncAndThen(accountId => config.identity.getIdentity(accountId));
         },
     };
 };

package/dist/accountService.spec.d.ts

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

package/dist/accountService.spec.js

@@ -0,0 +1,36 @@
+import { toHex } from '@novasamatech/scale';
+import { okAsync } from 'neverthrow';
+import { AccountId } from 'polkadot-api';
+import { describe, expect, it, vi } from 'vitest';
+import { createAccountService } from './accountService.js';
+const ADDRESS = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'; // Alice, SS58
+const HEX_ACCOUNT_ID = toHex(AccountId().enc(ADDRESS));
+function identityFor(accountId) {
+    return {
+        accountId,
+        fullUsername: 'alice',
+        liteUsername: 'alice.01',
+        credibility: { type: 'Lite' },
+        identifierKey: `0x${'ab'.repeat(32)}`,
+    };
+}
+const stubIdentity = (resolve) => vi.fn(accountId => okAsync(resolve(accountId)));
+const serviceWith = (getIdentity) => createAccountService({ identityEndpoint: 'https://example.invalid', identity: { getIdentity } });
+describe('accountService.getConsumerInfo', () => {
+    it('looks the account up by hex account id and returns its identity', async () => {
+        const getIdentity = stubIdentity(identityFor);
+        const result = await serviceWith(getIdentity).getConsumerInfo(ADDRESS);
+        expect(getIdentity).toHaveBeenCalledWith(HEX_ACCOUNT_ID);
+        expect(result._unsafeUnwrap()).toEqual(identityFor(HEX_ACCOUNT_ID));
+    });
+    it('resolves to null when the account has no consumer record', async () => {
+        const service = serviceWith(stubIdentity(() => null));
+        expect((await service.getConsumerInfo(ADDRESS))._unsafeUnwrap()).toBeNull();
+    });
+    it('reports a malformed address as an error rather than throwing', async () => {
+        const getIdentity = stubIdentity(identityFor);
+        const result = await serviceWith(getIdentity).getConsumerInfo('not-an-address');
+        expect(result.isErr()).toBe(true);
+        expect(getIdentity).not.toHaveBeenCalled();
+    });
+});

package/dist/codec/identifierKey.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Resources.Consumers.identifier_key` — a peer's chat encryption key as the chain
+ * records it (CHAT-RFC-0004 §4).
+ *
+ * The 65-byte width predates X25519: it is what an uncompressed P-256 point occupied,
+ * and it stayed when the curve changed. Only the keypair type and the key width moved
+ * (0x04 + 64 → 0x00 + 32), so the field is still `SizedHex<65>` in runtime metadata.
+ *
+ * Padding is carried as a field because the RFC requires readers to ignore it rather
+ * than validate it. Decoding throws on a keypair type this SDK does not implement —
+ * `decodeIdentifierKey` in `accountService.ts` maps that to `null`, since a peer on a
+ * curve we can't encrypt to is a normal condition, not a fault.
+ */
+export declare const IdentifierKey: import("scale-ts").Codec<{
+    tag: "X25519";
+    value: {
+        key: Uint8Array<ArrayBufferLike>;
+        padding: Uint8Array<ArrayBufferLike>;
+    };
+}>;

package/dist/codec/identifierKey.js

@@ -0,0 +1,18 @@
+import { Bytes, Enum } from '@novasamatech/scale';
+import { Struct } from 'scale-ts';
+/**
+ * `Resources.Consumers.identifier_key` — a peer's chat encryption key as the chain
+ * records it (CHAT-RFC-0004 §4).
+ *
+ * The 65-byte width predates X25519: it is what an uncompressed P-256 point occupied,
+ * and it stayed when the curve changed. Only the keypair type and the key width moved
+ * (0x04 + 64 → 0x00 + 32), so the field is still `SizedHex<65>` in runtime metadata.
+ *
+ * Padding is carried as a field because the RFC requires readers to ignore it rather
+ * than validate it. Decoding throws on a keypair type this SDK does not implement —
+ * `decodeIdentifierKey` in `accountService.ts` maps that to `null`, since a peer on a
+ * curve we can't encrypt to is a normal condition, not a fault.
+ */
+export const IdentifierKey = Enum({
+    X25519: Struct({ key: Bytes(32), padding: Bytes(32) }),
+});

package/dist/codec/identifierKey.spec.d.ts

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

package/dist/codec/identifierKey.spec.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { IdentifierKey } from './identifierKey.js';
+// CHAT-RFC-0004 §4 container: keypair-type byte ++ key(32) ++ padding(32). Built by
+// hand rather than through the codec — encoding with the thing under test would assert
+// it agrees with itself, not with the RFC. Matches Android `AccountEcdhKeyScaleTest`.
+const container = (keypairType, key, padding = new Uint8Array(32)) => {
+    const out = new Uint8Array(65);
+    out[0] = keypairType;
+    out.set(key, 1);
+    out.set(padding, 33);
+    return out;
+};
+const KEY = new Uint8Array(32).fill(0xab);
+describe('IdentifierKey', () => {
+    it('reads the x25519 key out of the container', () => {
+        expect(IdentifierKey.dec(container(0x00, KEY)).value.key).toStrictEqual(KEY);
+    });
+    it('ignores the padding, as the RFC requires', () => {
+        expect(IdentifierKey.dec(container(0x00, KEY, new Uint8Array(32).fill(0x7f))).value.key).toStrictEqual(KEY);
+    });
+    it('round-trips', () => {
+        const value = { tag: 'X25519', value: { key: KEY, padding: new Uint8Array(32) } };
+        expect(IdentifierKey.enc(value)).toStrictEqual(container(0x00, KEY));
+        expect(IdentifierKey.dec(IdentifierKey.enc(value))).toStrictEqual(value);
+    });
+    it('rejects a keypair type this SDK does not implement', () => {
+        expect(() => IdentifierKey.dec(container(0x04, KEY))).toThrow();
+    });
+    // The container width is not the key width — reading the field as a bare X25519 key
+    // is what broke peer lookup for every account.
+    it('rejects a bare 32-byte key', () => {
+        expect(() => IdentifierKey.dec(KEY)).toThrow();
+    });
+});

package/dist/codec/localMessage.d.ts

@@ -1,11 +1,11 @@
 export declare const OutgoingStatus: import("scale-ts").Codec<"new" | "sent" | "delivered">;
 export declare const IncomingStatus: import("scale-ts").Codec<"new" | "seen">;
 export declare const LocalStatus: import("scale-ts").Codec<{
-    tag: "outgoing";
-    value: "new" | "sent" | "delivered";
-} | {
     tag: "incoming";
     value: "new" | "seen";
+} | {
+    tag: "outgoing";
+    value: "new" | "sent" | "delivered";
 }>;
 export declare const LocalMessage: import("scale-ts").Codec<{
     remote: {
@@ -263,11 +263,11 @@ export declare const LocalMessage: import("scale-ts").Codec<{
     };
     peerId: import("@novasamatech/statement-store").AccountId;
     status: {
-        tag: "outgoing";
-        value: "new" | "sent" | "delivered";
-    } | {
         tag: "incoming";
         value: "new" | "seen";
+    } | {
+        tag: "outgoing";
+        value: "new" | "sent" | "delivered";
     };
     order: bigint;
 }>;

package/dist/index.d.ts

@@ -1 +1,2 @@
+export type { Credibility, Identity, IdentitySource } from './accountService.js';
 export { createAccountService } from './accountService.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-chat",
   "type": "module",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Host statement store chat integration",
   "license": "Apache-2.0",
   "repository": {
@@ -11,9 +11,6 @@
   "keywords": [
     "polkadot"
   ],
-  "scripts": {
-    "papi:update": "papi update"
-  },
   "main": "dist/index.js",
   "exports": {
     "./package.json": "./package.json",
@@ -40,11 +37,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/scale": "0.9.1",
-    "@novasamatech/statement-store": "0.9.1",
-    "@novasamatech/storage-adapter": "0.9.1",
+    "@novasamatech/host-papp": "0.9.2",
+    "@novasamatech/scale": "0.9.2",
+    "@novasamatech/statement-store": "0.9.2",
+    "@novasamatech/storage-adapter": "0.9.2",
     "nanoid": "6.0.0",
-    "neverthrow": "^8.2.0"
+    "neverthrow": "^8.2.0",
+    "polkadot-api": ">=2"
   },
   "publishConfig": {
     "access": "public"