@parity/product-sdk-terminal 0.3.1 → 0.4.0

package/README.md

@@ -112,9 +112,88 @@ File-based storage adapter for Node.js. Data persists in `storageDir` (defaults
 
 Waits for the session list to emit at least one entry, or resolves with `[]` after `timeoutMs`.
 
-## Allowance management (`./host` subpath)
+## Allowance signers — the canonical path
 
-For CLIs that need to write to Bulletin / Statement Store / Asset Hub smart contracts: the QR-paired mobile wallet is the Account Holder, the CLI plays the Host role, and `@parity/product-sdk-terminal/host` exposes that Host-runner surface (the [RFC-10](https://github.com/paritytech/triangle-js-sdks/blob/valentunn-rfc-0010/docs/rfcs/0010-allowance.md) Accounts Protocol companion, an on-disk allowance-key cache, and a local sr25519 signer over the cached keys).
+For CLIs that need to write to Bulletin or publish to the Statement Store: ask the paired wallet for an allowance slot, get a `PolkadotSigner` back, sign extrinsics with it. This is what most consumers want.
+
+```ts
+import {
+    createTerminalAdapter,
+    getBulletinSigner,
+    getStatementStoreProver,
+    waitForSessions,
+} from "@parity/product-sdk-terminal";
+
+const adapter = createTerminalAdapter({ appId: "my-cli" });
+
+// ...QR pair the phone, wait for the session...
+await waitForSessions(adapter);
+
+// First call prompts the wallet for an allowance slot; subsequent calls
+// return the cached slot key — no wire round-trip.
+const bulletinSigner = await getBulletinSigner(adapter, "my-cli.dot");
+await bulletinClient.tx.TransactionStorage.store({ data }).signAndSubmit(bulletinSigner);
+
+// Same idea, returns a StatementProver for `@novasamatech/statement-store` writes.
+const prover = await getStatementStoreProver(adapter, "my-cli.dot");
+```
+
+### `getBulletinSigner(adapter, productId, sessionId?): Promise<PolkadotSigner>`
+
+### `getStatementStoreProver(adapter, productId, sessionId?): Promise<StatementProver>`
+
+Both default `sessionId` to the only paired session. With zero or more than one paired sessions and no explicit id, both throw `AllowanceError` with `reason: 'NoSession'`. Pass an explicit `sessionId` to disambiguate.
+
+Failures from the host (`Rejected`, `NotAvailable`, codec drift) surface as `AllowanceError`:
+
+```ts
+import { AllowanceError } from "@parity/product-sdk-terminal";
+
+try {
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+} catch (err) {
+    if (err instanceof AllowanceError && err.reason === "Rejected") {
+        // user denied the allowance request on the phone
+    }
+    throw err;
+}
+```
+
+Behind the scenes both helpers wrap `adapter.allowance` (inherited from host-papp's `PappAdapter`) and unwrap its neverthrow `ResultAsync` into a throwing `Promise`. If you want to keep neverthrow's `.match()` / `.mapErr()` ergonomics or need explicit multi-session handling, call `adapter.allowance.getBulletinSigner(sessionId, productId)` / `getStatementStoreProver(...)` directly.
+
+### Cache-only probes — `hasBulletinAllowance` / `hasStatementStoreAllowance`
+
+For paths that must run silently — login health checks, "would calling `getBulletinSigner` prompt the phone?" decisions, readiness probes — use the cache-only variants. They read host-papp's on-disk allowance file directly and **never** trigger a wallet prompt.
+
+```ts
+import {
+    getBulletinSigner,
+    hasBulletinAllowance,
+} from "@parity/product-sdk-terminal";
+
+if (await hasBulletinAllowance(adapter, "my-cli.dot")) {
+    // happy path — fetch the signer without risking a wallet prompt
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+} else {
+    // tell the user a wallet prompt will fire, then call getBulletinSigner
+    console.log("Approve the allowance request on your phone…");
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+}
+```
+
+#### `hasBulletinAllowance(adapter, productId, sessionId?): Promise<boolean>`
+
+#### `hasStatementStoreAllowance(adapter, productId, sessionId?): Promise<boolean>`
+
+Resolves `true` when a slot key for `(sessionId, productId, resource)` is already cached on disk; `false` when it is not (file absent, or present with no matching entry). Same `sessionId` defaulting as the fetching helpers: defaults to the only paired session, throws `AllowanceError('NoSession')` for zero or multiple paired sessions without an explicit id.
+
+Rejects only on decrypt or decode failures — a corrupted cache file is a real failure, not a "no allowance" signal.
+
+> The cache-only check uses an internal mirror of host-papp's `AllowanceRepository` codec because host-papp doesn't expose a public probe today. We'll switch to the upstream API when one ships; the public surface (`hasBulletinAllowance` / `hasStatementStoreAllowance`) won't change.
+
+## Allowance management — manual cache + AP control (`./host` subpath)
+
+For CLIs that need finer control — pre-allocating multiple resources in one wallet prompt, inspecting the cache before round-tripping, or building a signer over a cached key without consulting the wallet — the `@parity/product-sdk-terminal/host` subpath exposes the lower-level Host-runner surface (the [RFC-10](https://github.com/paritytech/triangle-js-sdks/blob/valentunn-rfc-0010/docs/rfcs/0010-allowance.md) Accounts Protocol companion, an on-disk allowance-key cache, and a local sr25519 signer over the cached keys). Most CLIs don't need this — start with `getBulletinSigner` / `getStatementStoreProver` above.
 
 ```ts
 import {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { T as TerminalAdapter } from './adapter-Dt3ryKnw.js';
 export { a as TerminalAdapterOptions, c as createTerminalAdapter } from './adapter-Dt3ryKnw.js';
 import { UserSession } from '@novasamatech/host-papp';
-export { HostMetadata, PairingStatus, PappAdapter, SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
+export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
 import { PolkadotSigner } from 'polkadot-api';
+import { StatementProver } from '@novasamatech/statement-store';
 import { StorageAdapter } from '@novasamatech/storage-adapter';
 
 /**
@@ -100,6 +101,81 @@ declare function createSessionSigner(session: UserSession, adapter: TerminalAdap
  */
 declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef): PolkadotSigner;
 
+/**
+ * Get a `PolkadotSigner` for a Bulletin allowance slot.
+ *
+ * Allocates an allowance slot via the paired wallet (or returns the cached
+ * one), derives the slot-account keypair, and returns a `PolkadotSigner`
+ * that signs Bulletin extrinsics with it. Replaces the manual
+ * `requestResourceAllocation` + `createSlotAccountSigner` two-step for the
+ * common case.
+ *
+ * @param adapter Terminal adapter.
+ * @param productId The product id the slot is allocated under. Passed to the
+ *   host as the calling product id in the allowance request.
+ * @param sessionId Paired session to allocate against. Defaults to the only
+ *   paired session; throws `AllowanceError('NoSession')` when zero or more
+ *   than one sessions are paired and no explicit id is supplied.
+ * @throws {AllowanceError} On rejection, missing session, host-side failure,
+ *   or unexpected response shape.
+ *
+ * @example
+ * ```ts
+ * import { createTerminalAdapter, getBulletinSigner } from "@parity/product-sdk-terminal";
+ *
+ * const adapter = createTerminalAdapter({ appId: "my-cli" });
+ * // ... QR pair, wait for session ...
+ * const signer = await getBulletinSigner(adapter, "my-cli.dot");
+ * await client.bulletin.tx.TransactionStorage.store({ data }).signAndSubmit(signer);
+ * ```
+ */
+declare function getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<PolkadotSigner>;
+/**
+ * Get a `StatementProver` for a statement-store allowance slot.
+ *
+ * Allocates an allowance slot via the paired wallet (or returns the cached
+ * one) and returns the upstream `StatementProver` for the slot. Use when
+ * publishing statements through `@novasamatech/statement-store` without
+ * holding a long-lived key yourself.
+ *
+ * @param adapter Terminal adapter.
+ * @param productId The product id the slot is allocated under.
+ * @param sessionId Paired session to allocate against. Defaults to the only
+ *   paired session; throws `AllowanceError('NoSession')` when zero or more
+ *   than one sessions are paired and no explicit id is supplied.
+ * @throws {AllowanceError} On rejection, missing session, host-side failure,
+ *   or unexpected response shape.
+ */
+declare function getStatementStoreProver(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<StatementProver>;
+/**
+ * Cache-only probe for a Bulletin allowance slot. Resolves `true` when a
+ * slot key for `(sessionId, productId, bulletin)` is already cached on
+ * disk; `false` when it is not. Never prompts the paired wallet.
+ *
+ * Pair with {@link getBulletinSigner} for the "check first, fetch only
+ * if needed" flow:
+ *
+ * @example
+ * ```ts
+ * if (await hasBulletinAllowance(adapter, "my-cli.dot")) {
+ *     // happy path — fetch the signer without risking a wallet prompt
+ *     const signer = await getBulletinSigner(adapter, "my-cli.dot");
+ * } else {
+ *     // tell the user a wallet prompt will fire, then call getBulletinSigner
+ * }
+ * ```
+ */
+declare function hasBulletinAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>;
+/**
+ * Cache-only probe for a Statement Store allowance slot. Resolves `true`
+ * when a slot key for `(sessionId, productId, statementStore)` is already
+ * cached on disk; `false` when it is not. Never prompts the paired wallet.
+ *
+ * Pair with {@link getStatementStoreProver} for the "check first, fetch
+ * only if needed" flow.
+ */
+declare function hasStatementStoreAllowance(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<boolean>;
+
 /**
  * Helpers for working with persisted sessions on a `TerminalAdapter`.
  */
@@ -152,4 +228,4 @@ declare function renderQrCode(data: string, options?: QrRenderOptions): Promise<
  */
 declare function createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter;
 
-export { type ProductAccountRef, type QrRenderOptions, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, renderQrCode, waitForSessions };
+export { type ProductAccountRef, type QrRenderOptions, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, getBulletinSigner, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, waitForSessions };

package/dist/index.js

@@ -1,5 +1,6 @@
 import {
-  createNodeStorageAdapter
+  createNodeStorageAdapter,
+  sanitizeKey
 } from "./chunk-GHOFKVUG.js";
 
 // src/adapter.ts
@@ -616,6 +617,250 @@ var makeSession2;
 var ext2;
 var fakeAdapter2;
 
+// src/allowance.ts
+import { AllowanceError } from "@novasamatech/host-papp";
+
+// src/allowance-cache.ts
+import { gcm } from "@noble/ciphers/aes.js";
+import { blake2b } from "@noble/hashes/blake2.js";
+import { fromHex, toHex } from "@polkadot-api/utils";
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { Bytes, Enum, Struct, Vector, _void, str } from "scale-ts";
+var AllowanceResourceKindCodec = Enum({
+  bulletin: _void,
+  statementStore: _void
+});
+var StoredAllowanceEntryCodec = Struct({
+  productId: str,
+  resource: AllowanceResourceKindCodec,
+  slotAccountKey: Bytes()
+});
+var StoredAllowancesCodec = Vector(StoredAllowanceEntryCodec);
+function getAes(appId) {
+  const key = blake2b(new TextEncoder().encode(appId), { dkLen: 16 });
+  const nonce = blake2b(new TextEncoder().encode("nonce"), { dkLen: 32 });
+  return gcm(key, nonce);
+}
+function allowanceFilePath(storageDir, appId, sessionId) {
+  return join(storageDir, `${sanitizeKey(appId, `AllowanceKeys_${sessionId}`)}.json`);
+}
+async function readStoredAllowances(storageDir, appId, sessionId) {
+  let hex;
+  try {
+    hex = await readFile(allowanceFilePath(storageDir, appId, sessionId), "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+  const decrypted = getAes(appId).decrypt(fromHex(hex));
+  return StoredAllowancesCodec.dec(decrypted);
+}
+
+// src/allowance.ts
+function resolveSessionId(adapter, sessionId) {
+  if (sessionId) return sessionId;
+  const sessions = adapter.sessions.sessions.read();
+  if (sessions.length === 0) {
+    throw new AllowanceError("NoSession", "No paired session \u2014 pair a phone first.");
+  }
+  if (sessions.length > 1) {
+    throw new AllowanceError(
+      "NoSession",
+      `Multiple paired sessions (${sessions.length}) \u2014 pass an explicit sessionId.`
+    );
+  }
+  return sessions[0].id;
+}
+async function getBulletinSigner(adapter, productId, sessionId) {
+  const resolvedSessionId = resolveSessionId(adapter, sessionId);
+  return adapter.allowance.getBulletinSigner(resolvedSessionId, productId).match(
+    (signer) => signer,
+    (err) => {
+      throw err;
+    }
+  );
+}
+async function getStatementStoreProver(adapter, productId, sessionId) {
+  const resolvedSessionId = resolveSessionId(adapter, sessionId);
+  return adapter.allowance.getStatementStoreProver(resolvedSessionId, productId).match(
+    (prover) => prover,
+    (err) => {
+      throw err;
+    }
+  );
+}
+async function hasAllowanceForResource(adapter, productId, resource, sessionId) {
+  const resolvedSessionId = resolveSessionId(adapter, sessionId);
+  if (adapter.storageDir === void 0) {
+    return false;
+  }
+  const entries = await readStoredAllowances(
+    adapter.storageDir,
+    adapter.appId,
+    resolvedSessionId
+  );
+  return entries.some(
+    (entry) => entry.productId === productId && entry.resource.tag === resource
+  );
+}
+async function hasBulletinAllowance(adapter, productId, sessionId) {
+  return hasAllowanceForResource(adapter, productId, "bulletin", sessionId);
+}
+async function hasStatementStoreAllowance(adapter, productId, sessionId) {
+  return hasAllowanceForResource(adapter, productId, "statementStore", sessionId);
+}
+if (void 0) {
+  let makeAdapter = function(opts) {
+    return {
+      sessions: {
+        sessions: {
+          read: () => opts.sessions
+        }
+      },
+      allowance: {
+        getBulletinSigner: opts.getBulletinSigner ?? vi.fn(() => ok({})),
+        getStatementStoreProver: opts.getStatementStoreProver ?? vi.fn(() => ok({}))
+      }
+      // The convenience never touches the rest of the adapter; leave it unstubbed.
+    };
+  };
+  makeAdapter2 = makeAdapter;
+  const { describe, test, expect, vi } = void 0;
+  const { ok, err } = await null;
+  describe("getBulletinSigner \u2014 sessionId defaulting", () => {
+    test("uses the only paired session when sessionId is omitted", async () => {
+      const fakeSigner = { _tag: "signer" };
+      const getBulletinSignerFn = vi.fn(() => ok(fakeSigner));
+      const adapter = makeAdapter({
+        sessions: [{ id: "sess-only" }],
+        getBulletinSigner: getBulletinSignerFn
+      });
+      const result = await getBulletinSigner(adapter, "my-app.dot");
+      expect(result).toBe(fakeSigner);
+      expect(getBulletinSignerFn).toHaveBeenCalledWith("sess-only", "my-app.dot");
+    });
+    test("uses the explicit sessionId when supplied", async () => {
+      const fakeSigner = { _tag: "signer" };
+      const getBulletinSignerFn = vi.fn(() => ok(fakeSigner));
+      const adapter = makeAdapter({
+        sessions: [{ id: "sess-a" }, { id: "sess-b" }],
+        getBulletinSigner: getBulletinSignerFn
+      });
+      await getBulletinSigner(adapter, "my-app.dot", "sess-b");
+      expect(getBulletinSignerFn).toHaveBeenCalledWith("sess-b", "my-app.dot");
+    });
+    test("throws AllowanceError('NoSession') when zero sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [] });
+      await expect(getBulletinSigner(adapter, "my-app.dot")).rejects.toBeInstanceOf(
+        AllowanceError
+      );
+      await expect(getBulletinSigner(adapter, "my-app.dot")).rejects.toMatchObject({
+        reason: "NoSession"
+      });
+    });
+    test("throws AllowanceError('NoSession') when multiple sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [{ id: "a" }, { id: "b" }] });
+      await expect(getBulletinSigner(adapter, "my-app.dot")).rejects.toBeInstanceOf(
+        AllowanceError
+      );
+      await expect(getBulletinSigner(adapter, "my-app.dot")).rejects.toMatchObject({
+        reason: "NoSession"
+      });
+    });
+  });
+  describe("getBulletinSigner \u2014 error unwrapping", () => {
+    test("rethrows the AllowanceError from the underlying service as a thrown exception", async () => {
+      const underlyingErr = new AllowanceError("Rejected", "user said no");
+      const adapter = makeAdapter({
+        sessions: [{ id: "s" }],
+        getBulletinSigner: vi.fn(() => err(underlyingErr))
+      });
+      await expect(getBulletinSigner(adapter, "p")).rejects.toBe(underlyingErr);
+    });
+  });
+  describe("getStatementStoreProver \u2014 same defaulting", () => {
+    test("uses the only paired session when sessionId is omitted", async () => {
+      const fakeProver = { _tag: "prover" };
+      const getStatementStoreProverFn = vi.fn(() => ok(fakeProver));
+      const adapter = makeAdapter({
+        sessions: [{ id: "sess-only" }],
+        getStatementStoreProver: getStatementStoreProverFn
+      });
+      const result = await getStatementStoreProver(adapter, "my-app.dot");
+      expect(result).toBe(fakeProver);
+      expect(getStatementStoreProverFn).toHaveBeenCalledWith("sess-only", "my-app.dot");
+    });
+    test("uses the explicit sessionId when supplied", async () => {
+      const fakeProver = { _tag: "prover" };
+      const getStatementStoreProverFn = vi.fn(() => ok(fakeProver));
+      const adapter = makeAdapter({
+        sessions: [{ id: "sess-a" }, { id: "sess-b" }],
+        getStatementStoreProver: getStatementStoreProverFn
+      });
+      await getStatementStoreProver(adapter, "my-app.dot", "sess-b");
+      expect(getStatementStoreProverFn).toHaveBeenCalledWith("sess-b", "my-app.dot");
+    });
+    test("throws AllowanceError('NoSession') when zero sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [] });
+      await expect(getStatementStoreProver(adapter, "my-app.dot")).rejects.toBeInstanceOf(
+        AllowanceError
+      );
+      await expect(getStatementStoreProver(adapter, "my-app.dot")).rejects.toMatchObject({
+        reason: "NoSession"
+      });
+    });
+    test("throws AllowanceError('NoSession') when multiple sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [{ id: "a" }, { id: "b" }] });
+      await expect(getStatementStoreProver(adapter, "my-app.dot")).rejects.toBeInstanceOf(
+        AllowanceError
+      );
+      await expect(getStatementStoreProver(adapter, "my-app.dot")).rejects.toMatchObject({
+        reason: "NoSession"
+      });
+    });
+  });
+  describe("getStatementStoreProver \u2014 error unwrapping", () => {
+    test("rethrows the AllowanceError from the underlying service as a thrown exception", async () => {
+      const underlyingErr = new AllowanceError("Rejected", "user said no");
+      const adapter = makeAdapter({
+        sessions: [{ id: "s" }],
+        getStatementStoreProver: vi.fn(() => err(underlyingErr))
+      });
+      await expect(getStatementStoreProver(adapter, "p")).rejects.toBe(underlyingErr);
+    });
+  });
+  describe("has*Allowance \u2014 sessionId defaulting + storageDir fallback", () => {
+    test("hasBulletinAllowance throws AllowanceError('NoSession') when zero sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [] });
+      await expect(hasBulletinAllowance(adapter, "p")).rejects.toBeInstanceOf(AllowanceError);
+      await expect(hasBulletinAllowance(adapter, "p")).rejects.toMatchObject({
+        reason: "NoSession"
+      });
+    });
+    test("hasBulletinAllowance returns false (conservative) when storageDir is undefined", async () => {
+      const adapter = makeAdapter({ sessions: [{ id: "sess-only" }] });
+      expect(await hasBulletinAllowance(adapter, "p")).toBe(false);
+    });
+    test("hasStatementStoreAllowance throws AllowanceError('NoSession') when zero sessions and no id", async () => {
+      const adapter = makeAdapter({ sessions: [] });
+      await expect(hasStatementStoreAllowance(adapter, "p")).rejects.toBeInstanceOf(
+        AllowanceError
+      );
+    });
+    test("hasStatementStoreAllowance returns false (conservative) when storageDir is undefined", async () => {
+      const adapter = makeAdapter({ sessions: [{ id: "sess-only" }] });
+      expect(await hasStatementStoreAllowance(adapter, "p")).toBe(false);
+    });
+  });
+}
+var makeAdapter2;
+
+// src/index.ts
+import { AllowanceError as AllowanceError2 } from "@novasamatech/host-papp";
+
 // src/sessions.ts
 function waitForSessions(adapter, timeoutMs = 3e3) {
   return new Promise((resolve) => {
@@ -763,12 +1008,17 @@ if (void 0) {
   });
 }
 export {
+  AllowanceError2 as AllowanceError,
   SS_PASEO_STABLE_STAGE_ENDPOINTS,
   SS_STABLE_STAGE_ENDPOINTS,
   createNodeStorageAdapter,
   createSessionSigner,
   createSessionSignerForAccount,
   createTerminalAdapter,
+  getBulletinSigner,
+  getStatementStoreProver,
+  hasBulletinAllowance,
+  hasStatementStoreAllowance,
   renderQrCode,
   waitForSessions
 };