@coordination-network/user-client 0.0.1 → 0.0.2

package/README.md

@@ -20,10 +20,10 @@ console.log(networkId) // 0x-prefixed bytes32
 console.log(displayMetaStealthAddress) // "st:eth:0x..."
 
 // InMemoryIdentityRegistry and InMemoryMemberServer are test/demo fakes standing in for the
-// registry's read model and the network member's server. A real deployment uses
-// network-member-client's IdentityRegistryClient as the RegistryReader and an HTTP client for the
-// member server's registration endpoint as the RegistrationSubmitter — see "Dependency-injection
-// seams" below.
+// registry's read model and the network member's server. A real deployment splits this across
+// two processes: the holder's app signs the request and hands it to the network member's app,
+// which submits it to its own member server, carrying that server's own token — see
+// "Dependency-injection seams" below.
 const registry = new InMemoryIdentityRegistry()
 const memberServer = new InMemoryMemberServer(registry, { chainId: 1, verifyingContract: "0x..." })
 
@@ -58,7 +58,7 @@ if (result.status === "registered") {
 | `InMemoryIdentityRegistry`        | class    | In-memory `RegistryReader` fake for tests/local dev. `registerIdentity` is write-once.                                                                                                                                                     | `registerIdentity` throws `SubmissionFailedError` (`InvalidMetaStealthAddressLength` or `AlreadyRegistered`).            |
 | `InMemoryMemberServer`            | class    | In-memory `RegistrationSubmitter` fake standing in for an approved network member's server.                                                                                                                                                | `submit` throws `SubmissionFailedError` on `InvalidRegistrationRequest` or `AlreadyRegistered`.                          |
 | `createHttpRegistrationSubmitter` | function | Builds a `RegistrationSubmitter` that POSTs to a member server's `/v1/registrations` endpoint over `fetch`.                                                                                                                                | `HttpSubmissionError` for every non-submitted response and on a network failure.                                         |
-| `HttpSubmissionError`             | class    | Extends `SubmissionFailedError`. Carries `status`, `reason` (`"alreadyRegistered" \| "rejected" \| "unavailable" \| "network" \| "invalidResponse"`), and, where the server sent them, `serverCode`/`metaStealthAddress`/`matchesRequest`. | —                                                                                                                        |
+| `HttpSubmissionError`             | class    | Extends `SubmissionFailedError`. Carries `status`, `reason` (`"alreadyRegistered" \| "rejected" \| "unavailable" \| "unauthorized" \| "network" \| "invalidResponse"`), and when sent, `serverCode`/`metaStealthAddress`/`matchesRequest`. | —                                                                                                                        |
 | `UserClientError`                 | class    | Base error class for this package, discriminated by `code: UserClientErrorCode`.                                                                                                                                                           | —                                                                                                                        |
 | `InvalidMetaStealthAddressError`  | class    | Re-exported from `@coordination-network/identity`. Extends its `KeygenError`, not `UserClientError`, and names the malformed key. Thrown when encoding a meta-stealth address.                                                             | —                                                                                                                        |
 | `SubmissionFailedError`           | class    | Extends `UserClientError` (`code: "SUBMISSION_FAILED"`). Thrown when a `RegistrationSubmitter.submit` call fails, including on a lost duplicate-registration race (see below).                                                             | —                                                                                                                        |
@@ -79,26 +79,34 @@ git diff --exit-code packages/user-client/tests/vectors/registration-vectors.jso
 
 **Implementing `RegistryReader` against a chain.** `IdentityRegistry` stores the mapping as `bytes`, so its generated getter answers an unregistered `networkId` with empty bytes. viem and ethers surface that as `"0x"`, and the port requires `null`. `register()` rejects anything that is neither `null` nor a 66-byte entry rather than reading it as an existing registration, but an adapter should map the empty answer to `null` itself.
 
-`RegistryReader` (read an identity's current registration) and `RegistrationSubmitter` (submit a new one) are dependency-injection interfaces, not concrete transports. On chain, writes are gated on an approved network member's Semaphore proof (`IdentityRegistry.registerIdentity(networkId, metaStealthAddress, proof)`; the proof comes from `@coordination-network/network-member-proof`). The user's signature is consent the member server verifies off chain with `verifyRegistrationRequest` before it builds the proof and submits; the contract never reads it. No credential check sits on this path (#46). The gas-sponsorship model is settled ([`specs/05-stealth-addresses.md`](../../specs/05-stealth-addresses.md), "Gas sponsorship"): registration stays self-submitted and self-paid by the network-member server, and only post-registration transactions go through the shared amortised Semaphore paymaster. Any future transport — a relayer, a meta-transaction relay, a bundler — plugs in as a new `RegistrationSubmitter` implementation without changing this package's API. `InMemoryIdentityRegistry` and `InMemoryMemberServer` are in-memory fakes for tests and local development; `@coordination-network/network-member-client`'s `IdentityRegistryClient` satisfies `RegistryReader` (it maps the getter's empty bytes to `null`); `createHttpRegistrationSubmitter` (below) is the real `RegistrationSubmitter`, an HTTP client for `apps/issuer-service`'s `POST /v1/registrations`, which verifies consent with `verifyRegistrationRequest` and submits it via `network-member-client`'s `submitRegistration`.
+`RegistryReader` (read an identity's current registration) and `RegistrationSubmitter` (submit a new one) are dependency-injection interfaces, not concrete transports. On chain, writes are gated on an approved network member's Semaphore proof (`IdentityRegistry.registerIdentity(networkId, metaStealthAddress, proof)`; the proof comes from `@coordination-network/network-member-proof`). The user's signature is consent the member server verifies off chain with `verifyRegistrationRequest` before it builds the proof and submits; the contract never reads it. No credential check sits on this path (#46). The gas-sponsorship model is settled ([`specs/05-stealth-addresses.md`](../../specs/05-stealth-addresses.md), "Gas sponsorship"): registration stays self-submitted and self-paid by the network-member server, and only post-registration transactions go through the shared amortised Semaphore paymaster. Any future transport — a relayer, a meta-transaction relay, a bundler — plugs in as a new `RegistrationSubmitter` implementation without changing this package's API. `InMemoryIdentityRegistry` and `InMemoryMemberServer` are in-memory fakes for tests and local development; `@coordination-network/network-member-client`'s `IdentityRegistryClient` satisfies `RegistryReader` (it maps the getter's empty bytes to `null`); `createHttpRegistrationSubmitter` (below) is the member-side HTTP `RegistrationSubmitter`, for a process the organisation runs that holds its `memberServerToken`; it posts to `apps/issuer-service`'s `POST /v1/registrations`, which verifies consent with `verifyRegistrationRequest` and submits it via `network-member-client`'s `submitRegistration`.
 
 ### HTTP submitter
 
-`createHttpRegistrationSubmitter({ url })` POSTs the `RegistrationRequest` as JSON to `${url}/v1/registrations` and maps the member server's response onto this package's types:
+A member-side process calls `submitter.submit(request)` with the `RegistrationRequest` the holder already built and signed with this package's own `buildRegistrationRequest`. `createHttpRegistrationSubmitter({ url, memberServerToken })` POSTs that request as JSON to `${url}/v1/registrations` and maps the member server's response onto this package's types:
 
 ```typescript
 import { createHttpRegistrationSubmitter } from "@coordination-network/user-client"
 
-const submitter = createHttpRegistrationSubmitter({ url: "https://member.example" })
-const result = await register({ deviceSecret, registry, submitter, domain })
+const submitter = createHttpRegistrationSubmitter({
+    url: "https://member.example",
+    memberServerToken: process.env.MEMBER_SERVER_TOKEN
+})
+await submitter.submit(request)
 ```
 
-A `201` resolves `submit()` with `{ txHash }`. A `200` (the member server's `alreadyRegistered` response) throws `HttpSubmissionError` (`reason: "alreadyRegistered"`) carrying the registry's current `metaStealthAddress`; catch it and re-run `register()` — its own `registry.getIdentity` read will now see that entry and return the `alreadyRegistered` result instead. `400`, `503`, and a network failure throw `HttpSubmissionError` with `reason: "rejected"`, `"unavailable"` (with the server's own `serverCode`, if it sent one), and `"network"`, respectively. `HttpSubmissionError` never includes the request body or its signature.
+`memberServerToken` is the Network Member Server's own bearer token (`apps/issuer-service`'s `MEMBER_SERVER_TOKEN`), sent as `Authorization: Bearer <memberServerToken>` when set; the registration route now requires it. That token belongs to a member-side process the organisation itself runs, not to a holder — never pass one from a holder's wallet or app bundle.
+
+Don't pair the Quickstart's `register()` composition with a `createHttpRegistrationSubmitter` that holds `memberServerToken` anywhere but a trusted single process such as a local testbed; on a holder's device, give `register()` a `RegistrationSubmitter` that hands the signed request to the member's app instead.
+
+A `201` resolves `submit()` with `{ txHash }`. A `200` (the member server's `alreadyRegistered` response) throws `HttpSubmissionError` (`reason: "alreadyRegistered"`) carrying the registry's current `metaStealthAddress` and `matchesRequest`; a member-side caller has no device secret to re-run `register()` with, so treat those fields as the answer — the identity is already registered, and `matchesRequest` says whether it's already this request's address. A caller that is itself running `register()` (a trusted single process) can instead just re-run it: its own `registry.getIdentity` read will now see the entry and return the `alreadyRegistered` result instead. `400` throws `reason: "rejected"`; `401` (a missing or wrong `memberServerToken`) throws `reason: "unauthorized"`; `429` and `503` both throw `reason: "unavailable"` carrying the server's own `serverCode` (`"RATE_LIMITED"` for a `429`); and a network failure throws `reason: "network"`. `HttpSubmissionError` never includes the request body or its signature.
 
 ## Security notes
 
 - **`status: "registered"` means submitted, not confirmed.** `register()` returns as soon as the injected `RegistrationSubmitter` resolves. It does not wait for inclusion or check a receipt, and `receipt.txHash` is `null` for a submitter that queues rather than broadcasts. A transaction that is mined and reverts also resolves here.
 - **An existing entry is reported, not verified, and can change.** Only `registerIdentity` refuses a duplicate; an approved network member can `updateIdentity` or `removeIdentity` any entry at any time. If `alreadyRegistered` comes back with `matchesDerived: false`, this device's keys do not derive the meta-stealth address its `networkId` currently resolves to, and that is recoverable only through a member calling `updateIdentity`. A `matchesDerived: true` result is not permanent either — re-read `getIdentity` and compare against `metaStealthAddressFromKeys` whenever the mapping is load-bearing.
 - **Consent is checked by the member server, not the chain.** `IdentityRegistry` gates writes on a Semaphore proof, not on the user's signature. A member server that skips `verifyRegistrationRequest` can register any `metaStealthAddress` under any `networkId`, since its membership proof covers whatever pair it submits. Comparing `metaStealthAddress` with `derivedMetaStealthAddress` (the bullet above) is how a user detects that.
+- **`memberServerToken` leaking is worse than one bad registration.** Anyone who extracts it can act as that member on every member-side route, not just registration.
 - **Duplicate-registration races.** If two `register()` calls for the same `networkId` are in flight at once, both will see no existing registration and both will attempt `submit()`. The losing submission surfaces as a `SubmissionFailedError` (`AlreadyRegistered`, in `InMemoryMemberServer`'s case). The caller should simply retry `register()`: the retry's `registry.getIdentity` lookup will now find the winner's registration and return the `alreadyRegistered` result instead of erroring.
 - **React Native / Hermes.** `@coordination-network/identity`'s barrel loads on Hermes without a global `Buffer` — `onboard` and `register` don't need one. An app that also depends on something else expecting Node's `Buffer` may still want to set a polyfill globally for that code, but this package's own path does not require it.
 

package/dist/index.cjs

@@ -311,9 +311,11 @@ async function register(params) {
 
 /**
  * Thrown by {@link createHttpRegistrationSubmitter}. `alreadyRegistered`
- * carries the registry's current entry so a caller can re-run `register()`
- * and land in its own `alreadyRegistered` branch once that's visible to
- * `params.registry.getIdentity`.
+ * carries the registry's current `metaStealthAddress` and `matchesRequest`
+ * as the answer — a member-side caller has no device secret to re-run
+ * `register()` with. A caller that is itself running `register()` (a
+ * trusted single process) can instead just re-run it, since its own
+ * `registry.getIdentity` read will now return `alreadyRegistered`.
  */
 class HttpSubmissionError extends SubmissionFailedError {
     constructor(message, init) {
@@ -342,14 +344,17 @@ function parseTxHash(value) {
  * Never logs or throws the request body or its signature — only the response
  * status and, where sent, the server's own error code.
  */
-function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
+function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch, memberServerToken }) {
     return {
         async submit(request) {
             let response;
             try {
                 response = await fetchImpl(`${url}/v1/registrations`, {
                     method: "POST",
-                    headers: { "Content-Type": "application/json" },
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(memberServerToken === undefined ? {} : { Authorization: `Bearer ${memberServerToken}` })
+                    },
                     body: JSON.stringify(request)
                 });
             }
@@ -395,9 +400,15 @@ function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
                     reason: "rejected"
                 });
             }
-            if (response.status === 503) {
+            if (response.status === 401) {
+                throw new HttpSubmissionError("Registration submission was not authorized", {
+                    status: 401,
+                    reason: "unauthorized"
+                });
+            }
+            if (response.status === 429 || response.status === 503) {
                 throw new HttpSubmissionError("Registration service is unavailable", {
-                    status: 503,
+                    status: response.status,
                     reason: "unavailable",
                     serverCode: body?.code
                 });

package/dist/index.js

@@ -310,9 +310,11 @@ async function register(params) {
 
 /**
  * Thrown by {@link createHttpRegistrationSubmitter}. `alreadyRegistered`
- * carries the registry's current entry so a caller can re-run `register()`
- * and land in its own `alreadyRegistered` branch once that's visible to
- * `params.registry.getIdentity`.
+ * carries the registry's current `metaStealthAddress` and `matchesRequest`
+ * as the answer — a member-side caller has no device secret to re-run
+ * `register()` with. A caller that is itself running `register()` (a
+ * trusted single process) can instead just re-run it, since its own
+ * `registry.getIdentity` read will now return `alreadyRegistered`.
  */
 class HttpSubmissionError extends SubmissionFailedError {
     constructor(message, init) {
@@ -341,14 +343,17 @@ function parseTxHash(value) {
  * Never logs or throws the request body or its signature — only the response
  * status and, where sent, the server's own error code.
  */
-function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
+function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch, memberServerToken }) {
     return {
         async submit(request) {
             let response;
             try {
                 response = await fetchImpl(`${url}/v1/registrations`, {
                     method: "POST",
-                    headers: { "Content-Type": "application/json" },
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(memberServerToken === undefined ? {} : { Authorization: `Bearer ${memberServerToken}` })
+                    },
                     body: JSON.stringify(request)
                 });
             }
@@ -394,9 +399,15 @@ function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
                     reason: "rejected"
                 });
             }
-            if (response.status === 503) {
+            if (response.status === 401) {
+                throw new HttpSubmissionError("Registration submission was not authorized", {
+                    status: 401,
+                    reason: "unauthorized"
+                });
+            }
+            if (response.status === 429 || response.status === 503) {
                 throw new HttpSubmissionError("Registration service is unavailable", {
-                    status: 503,
+                    status: response.status,
                     reason: "unavailable",
                     serverCode: body?.code
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coordination-network/user-client",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Single-call onboarding and registration for the coordination network: derive device keys, encode the meta-stealth address, and register networkId -> metaStealthAddress on IdentityRegistry.",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,13 @@
     "build": "rimraf dist types && rollup -c rollup.config.mjs"
   },
   "dependencies": {
-    "@coordination-network/identity": "^0.0.1",
+    "@coordination-network/identity": "^0.0.2",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0"
   },
   "devDependencies": {
-    "@coordination-network/network-member-client": "^0.0.1",
-    "@coordination-network/network-member-proof": "^0.0.1",
+    "@coordination-network/network-member-client": "^0.0.2",
+    "@coordination-network/network-member-proof": "^0.0.2",
     "@rollup/plugin-typescript": "^12.3.0",
     "@semaphore-protocol/group": "4.14.3",
     "@semaphore-protocol/identity": "4.14.3",

package/src/http-submitter.ts

@@ -3,7 +3,8 @@ import { hexToBytes } from "./bytes"
 import { TX_HASH_LENGTH } from "./constants"
 import { SubmissionFailedError } from "./errors"
 
-export type HttpSubmissionReason = "alreadyRegistered" | "rejected" | "unavailable" | "network" | "invalidResponse"
+export type HttpSubmissionReason =
+    "alreadyRegistered" | "rejected" | "unavailable" | "unauthorized" | "network" | "invalidResponse"
 
 export interface HttpSubmissionErrorInit {
     status?: number
@@ -18,9 +19,11 @@ export interface HttpSubmissionErrorInit {
 
 /**
  * Thrown by {@link createHttpRegistrationSubmitter}. `alreadyRegistered`
- * carries the registry's current entry so a caller can re-run `register()`
- * and land in its own `alreadyRegistered` branch once that's visible to
- * `params.registry.getIdentity`.
+ * carries the registry's current `metaStealthAddress` and `matchesRequest`
+ * as the answer — a member-side caller has no device secret to re-run
+ * `register()` with. A caller that is itself running `register()` (a
+ * trusted single process) can instead just re-run it, since its own
+ * `registry.getIdentity` read will now return `alreadyRegistered`.
  */
 export class HttpSubmissionError extends SubmissionFailedError {
     readonly status?: number
@@ -43,6 +46,10 @@ export class HttpSubmissionError extends SubmissionFailedError {
 export interface HttpRegistrationSubmitterOptions {
     url: string
     fetch?: typeof fetch
+    /** Bearer token for the Network Member Server's member-side routes, sent as
+     *  `Authorization: Bearer <memberServerToken>` when set. The server's own token — never a
+     *  holder's, so it must not ship in a wallet or app bundle. */
+    memberServerToken?: string
 }
 
 interface SubmittedBody {
@@ -77,7 +84,8 @@ function parseTxHash(value: unknown): Hex | null {
  */
 export function createHttpRegistrationSubmitter({
     url,
-    fetch: fetchImpl = fetch
+    fetch: fetchImpl = fetch,
+    memberServerToken
 }: HttpRegistrationSubmitterOptions): RegistrationSubmitter {
     return {
         async submit(request: RegistrationRequest): Promise<SubmissionReceipt> {
@@ -85,7 +93,10 @@ export function createHttpRegistrationSubmitter({
             try {
                 response = await fetchImpl(`${url}/v1/registrations`, {
                     method: "POST",
-                    headers: { "Content-Type": "application/json" },
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(memberServerToken === undefined ? {} : { Authorization: `Bearer ${memberServerToken}` })
+                    },
                     body: JSON.stringify(request)
                 })
             } catch (error) {
@@ -134,9 +145,16 @@ export function createHttpRegistrationSubmitter({
                 })
             }
 
-            if (response.status === 503) {
+            if (response.status === 401) {
+                throw new HttpSubmissionError("Registration submission was not authorized", {
+                    status: 401,
+                    reason: "unauthorized"
+                })
+            }
+
+            if (response.status === 429 || response.status === 503) {
                 throw new HttpSubmissionError("Registration service is unavailable", {
-                    status: 503,
+                    status: response.status,
                     reason: "unavailable",
                     serverCode: (body as ErrorBody | null)?.code
                 })

package/types/index.d.ts

@@ -145,7 +145,7 @@ declare class InMemoryMemberServer implements RegistrationSubmitter {
 declare function onboard(deviceSecret: Uint8Array | Hex): Onboarding;
 declare function register(params: RegisterParams): Promise<RegisterResult>;
 
-type HttpSubmissionReason = "alreadyRegistered" | "rejected" | "unavailable" | "network" | "invalidResponse";
+type HttpSubmissionReason = "alreadyRegistered" | "rejected" | "unavailable" | "unauthorized" | "network" | "invalidResponse";
 interface HttpSubmissionErrorInit {
     status?: number;
     reason: HttpSubmissionReason;
@@ -158,9 +158,11 @@ interface HttpSubmissionErrorInit {
 }
 /**
  * Thrown by {@link createHttpRegistrationSubmitter}. `alreadyRegistered`
- * carries the registry's current entry so a caller can re-run `register()`
- * and land in its own `alreadyRegistered` branch once that's visible to
- * `params.registry.getIdentity`.
+ * carries the registry's current `metaStealthAddress` and `matchesRequest`
+ * as the answer — a member-side caller has no device secret to re-run
+ * `register()` with. A caller that is itself running `register()` (a
+ * trusted single process) can instead just re-run it, since its own
+ * `registry.getIdentity` read will now return `alreadyRegistered`.
  */
 declare class HttpSubmissionError extends SubmissionFailedError {
     readonly status?: number;
@@ -173,13 +175,17 @@ declare class HttpSubmissionError extends SubmissionFailedError {
 interface HttpRegistrationSubmitterOptions {
     url: string;
     fetch?: typeof fetch;
+    /** Bearer token for the Network Member Server's member-side routes, sent as
+     *  `Authorization: Bearer <memberServerToken>` when set. The server's own token — never a
+     *  holder's, so it must not ship in a wallet or app bundle. */
+    memberServerToken?: string;
 }
 /**
  * HTTP `RegistrationSubmitter` for `apps/issuer-service`'s `POST /v1/registrations`.
  * Never logs or throws the request body or its signature — only the response
  * status and, where sent, the server's own error code.
  */
-declare function createHttpRegistrationSubmitter({ url, fetch: fetchImpl }: HttpRegistrationSubmitterOptions): RegistrationSubmitter;
+declare function createHttpRegistrationSubmitter({ url, fetch: fetchImpl, memberServerToken }: HttpRegistrationSubmitterOptions): RegistrationSubmitter;
 
 export { DIGEST_LENGTH, EIP712_DOMAIN_TYPE, HttpSubmissionError, IDENTITY_REGISTRY_DOMAIN_NAME, IDENTITY_REGISTRY_DOMAIN_VERSION, InMemoryIdentityRegistry, InMemoryMemberServer, NETWORK_ID_LENGTH, REGISTER_IDENTITY_TYPE, REQUEST_VERSION, RegistryReadFailedError, SCHEME_ID, SIGNATURE_LENGTH, SubmissionFailedError, TX_HASH_LENGTH, UserClientError, buildRegistrationRequest, createHttpRegistrationSubmitter, identityRegistryDomainSeparator, metaStealthAddressFromKeys, onboard, register, registerIdentityDigest, registerIdentityStructHash, signRegisterIdentity, verifyRegistrationRequest };
 export type { ChainDomain, Hex, HttpRegistrationSubmitterOptions, HttpSubmissionErrorInit, HttpSubmissionReason, Onboarding, RegisterParams, RegisterResult, RegistrationRequest, RegistrationSubmitter, RegistryReader, SubmissionReceipt, UserClientErrorCode };