Headless pairing + signing hosts

[pgherveou]

Adds a truapi-host CLI with pairing-host and signing-host commands:
a TrUAPI host — the product side and the wallet side — you can spin up from the
command line and drive with a JS/TS script. It pairs over the real
paseo-next-v2 People-chain statement store (the same node an iOS/web client
uses); no local relay or node. (Plus the truapi-server work it needs — see below.)

Usage

Launch the two hosts (in two terminals, or background the first). The pairing
host serves a product and runs your script; the signing host answers the deeplink
it prints and signs:

# terminal 1 — pairing host: serves `myapp.dot`, runs the product script
truapi-host pairing-host --product-id myapp.dot --script whoami.ts
#   → prints:  PAIRING_DEEPLINK polkadotapp://pair?handshake=…

# terminal 2 — signing host: answers that deeplink and signs. The wallet mnemonic
# is --mnemonic, else $HOST_CLI_SIGNER_MNEMONIC, else the dev mnemonic (must be a
# registered LitePeople ring member).
truapi-host signing-host --deeplink 'polkadotapp://pair?handshake=…' --auto-accept

The script is top-level code; a thrown error fails the run:

// whoami.ts — top-level product script; `truapi` and `host` are injected globals
const login = await truapi.account.requestLogin({ reason: undefined });
if (!login.isOk() || login.value !== "Success") throw new Error("login failed");

// `truapi`: the @parity/truapi client, scoped to the host's --product-id
const user = await truapi.account.getUserId();
console.log("user id:", user.match((v) => v.primaryUsername, (e) => { throw e; }));

// `host`: keeps accounts in sync with --product-id — e.g. for a call that needs one:
//   truapi.signing.signRaw({ account: host.productAccount(0), payload: … })

Expected output (the signing host registers on-chain allowance, then both pair
and the script runs):

[pairing] FRAMES_LISTENING ws://127.0.0.1:9955
[pairing] PAIRING_DEEPLINK polkadotapp://pair?handshake=…
[signing] SIGNING_HOST_RING ring_index=16 members=255
[signing] SIGNING_HOST_ALLOWANCE wallet-sso seq=0 block=0x6fba67…
[signing] SIGNING_HOST_ALLOWANCE device   seq=1 block=0x529830…
[signing] SIGNING_HOST_READY
[pairing] user id: guestnrun.93

Both commands take --auto-accept; without it, every confirmation a web/iOS host
shows as a modal is prompted y/n on the CLI. The pairing host exits with the
script's status, so the command is the test.

Diagnose on-chain statement-store allowance for a mnemonic:

truapi-host alloc-check --lookback 100      # ring membership + free slot (read-only)

E2E

Two ready-made product scripts live in js/scripts/.

battery.ts — a signer gate (login + raw/payload signing, create-transaction,
entropy):

truapi-host pairing-host --product-id myapp.dot \
  --script rust/crates/truapi-host-cli/js/scripts/battery.ts --auto-accept

PASS  account.requestLogin         Success
PASS  account.getAccount           0xc0b6abd4f6b86dca
PASS  signing.signRaw(bytes)       0x4cc7eba6af60a905
PASS  signing.signRaw(message)     0x36d4735a9915dbbb
PASS  signing.signPayload          0x48ad551917975c8b
PASS  signing.createTransaction    210 chars
PASS  entropy.derive               0x6c79043d8bf65868
7/7 passed
GATE PASSED: 7 signer-critical cases

diagnosis.ts — runs the playground's own generated examples and writes
explorer/diagnosis-reports/headless.md. The examples are baked to
truapi-playground.dot, so serve that product:

truapi-host pairing-host --product-id truapi-playground.dot \
  --script rust/crates/truapi-host-cli/js/scripts/diagnosis.ts --auto-accept
# → 43 passed, 1 failed, 20 skipped (only the Chain/stop_transaction node limitation)

make headless builds the CLI + client; rust/crates/truapi-host-cli/e2e/run.sh
wraps a pairing host + signer (deeplink piped) for one-shot runs.

Roles (one truapi-host binary)

• pairing-host — seedless PairingHostRuntime; serves product frames and
  runs your --script with truapi injected.
• signing-host — wallet-local SigningHostRuntime; registers statement
  allowance on-chain, answers the handshake, and signs via the SSO responder.
• identity-check — probe which derivation of a mnemonic carries a username.
• alloc-check — diagnose (or --submit) on-chain statement-store allowance.

Both hosts default --statement-store to wss://paseo-people-next-system-rpc.polkadot.io.
Product ids must be a .dot/localhost identifier; the default is
headless-playground.dot.

Statement-store allowance (src/alloc/)

The real store enforces per-account allowance. The signing host grants it
on-chain exactly as a real client does, via an unsigned General (v5)
Resources.set_statement_store_account extrinsic (pallet 63 call 10) carrying a
bandersnatch ring-VRF membership proof. The native port covers:

• metadata-driven signed-extension encoding + the inherited-implication proof
  message (0x00 ‖ call ‖ Σtail.extra ‖ Σtail.implicit), pinned by a
  known-answer test to the live-verified vector;
• the ring-VRF one-shot proof (open/create via the verifiable prover);
• AsResourcesInfo + the General-v5 envelope;
• Members ring fetch (current index, paged RingKeys, included slice,
  ring_size → domain) and the SSS_SLOT slot scan;
• a minimal WS JSON-RPC client with author_submitAndWatchExtrinsic.

Before pairing, the signing host registers allowance for the two accounts that
submit statements — its own //wallet//sso account and the pairing host's
per-pairing device key — proving its LitePeople ring membership once, and waits
for the registrations to finalize (the store does not honor a fresh allowance
until then). The signing account must be an attested member; because a
long-lived account sits in an older ring, the host scans back from the current
ring index to find it.

statement_store_rpc::submit inspects the SubmitResult: only new/known
count as accepted, so NoAllowance/BadProof rejections surface instead of
being silently dropped.

truapi-server additions

• §B responder half: encode-side handshake helpers + responder codecs in
  host_logic/sso/, runtime/signing_host/sso_responder.rs.
• sign_payload and create_transaction on the signing host, with v4 extrinsic
  assembly (host_logic/transaction.rs).
• Product accounts + rootUserAccountId derive from //wallet (host-spec
  C.0/C.5) via an sr25519 hard-junction helper.
• Bandersnatch ring-VRF aliases (get_account_alias) via the verifiable crate
  (native-only; wasm unaffected).
• Lite-username attestation (host_logic/attestation.rs + CLI); get_user_id
  resolves a real People-chain username, and since SSO and identity share the
  People chain it always resolves.

Verification: cargo build/clippy -D warnings/test workspace-wide, cargo +nightly fmt --check, and make wasm all green; the full pairing + signer flow
passes live against paseo-next-v2, driven through the injected product script.

Notes for reviewers

• The signer mnemonic is read from --mnemonic / $HOST_CLI_SIGNER_MNEMONIC /
  a gitignored e2e/.env; it is not committed. The dev mnemonic works out of the
  box (ring member, username guestnrun.93).
• Not yet wired into make e2e-dotli.

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​reqwest@​0.12.28
	cargo/​tokio-tungstenite@​0.24.0

View full report