@coordination-network/user-client 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# `@coordination-network/user-client`
+
+Single-call onboarding and registration for the coordination network: derive a device's keys via `@coordination-network/identity`, encode the ERC-6538 meta-stealth address, and hand a signed registration request to the network member's server, which writes `networkId -> metaStealthAddress` on `IdentityRegistry`, deduped against an already-registered identity.
+
+## Install
+
+```bash
+yarn add @coordination-network/user-client
+```
+
+## Quickstart
+
+```typescript
+import { onboard, register, InMemoryIdentityRegistry, InMemoryMemberServer } from "@coordination-network/user-client"
+
+// Derive this device's keys, networkId, and meta-stealth address.
+const { networkId, displayMetaStealthAddress } = onboard(deviceSecret)
+
+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.
+const registry = new InMemoryIdentityRegistry()
+const memberServer = new InMemoryMemberServer(registry, { chainId: 1, verifyingContract: "0x..." })
+
+const result = await register({
+    deviceSecret,
+    registry,
+    submitter: memberServer,
+    domain: { chainId: 1, verifyingContract: "0x..." }
+})
+
+if (result.status === "registered") {
+    console.log(result.receipt.txHash)
+} else {
+    console.log("already registered as", result.metaStealthAddress)
+}
+```
+
+## API reference
+
+| Export                            | Kind     | Description                                                                                                                                                                                                                                | Throws                                                                                                                   |
+| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `onboard`                         | function | Derives keys from a device secret and returns `{ keys, networkId, metaStealthAddress, displayMetaStealthAddress }`.                                                                                                                        | `InvalidMetaStealthAddressError` if the derived spending/viewing public keys are malformed.                              |
+| `register`                        | function | Full flow: `onboard`, check for an existing registration, and submit if none exists.                                                                                                                                                       | `SubmissionFailedError`, `RegistryReadFailedError`, or `UserClientError` (`INVALID_INPUT`) on a malformed reader answer. |
+| `metaStealthAddressFromKeys`      | function | Encodes a `DerivedKeys` bundle's spending/viewing keys into the 66-byte ERC-6538 scheme-1 meta-stealth address. Delegates to `@coordination-network/identity`.                                                                             | `InvalidMetaStealthAddressError` on a malformed spending/viewing public key.                                             |
+| `displayMetaStealthAddress`       | function | Re-exported from `@coordination-network/identity` as `metaStealthAddressUri`. Formats a meta-stealth address hex string with the `st:eth:` display prefix.                                                                                 | —                                                                                                                        |
+| `identityRegistryDomainSeparator` | function | Computes the EIP-712 domain separator naming the `IdentityRegistry` deployment the consent is bound to.                                                                                                                                    | —                                                                                                                        |
+| `registerIdentityStructHash`      | function | Computes the EIP-712 `RegisterIdentity` struct hash for a `networkId`/`metaStealthAddress` pair.                                                                                                                                           | —                                                                                                                        |
+| `registerIdentityDigest`          | function | Computes the final EIP-712 digest (`keccak256(0x1901 \|\| domainSeparator \|\| structHash)`) signed and verified by the registration flow.                                                                                                 | —                                                                                                                        |
+| `signRegisterIdentity`            | function | Signs a digest with the account private key, returning a 65-byte `r \|\| s \|\| v` hex signature.                                                                                                                                          | —                                                                                                                        |
+| `buildRegistrationRequest`        | function | Builds a fully-signed `RegistrationRequest` from a `DerivedKeys` bundle and a `ChainDomain`.                                                                                                                                               | `InvalidMetaStealthAddressError` (via `metaStealthAddressFromKeys`).                                                     |
+| `verifyRegistrationRequest`       | function | Whether a member server pinned to `expected` should accept the request: field widths, a well-formed meta-stealth address, the domain, and a signer matching the full `networkId`. Returns `boolean`, never throws.                         | —                                                                                                                        |
+| `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`. | —                                                                                                                        |
+| `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).                                                             | —                                                                                                                        |
+| `RegistryReadFailedError`         | class    | Extends `UserClientError` (`code: "REGISTRY_READ_FAILED"`). Thrown when a `RegistryReader.getIdentity` call rejects.                                                                                                                       | —                                                                                                                        |
+
+## Meta-stealth-address encoding
+
+`metaStealthAddressFromKeys`, in `src/meta.ts`, adapts a `DerivedKeys` bundle onto `@coordination-network/identity`'s `encodeMetaStealthAddress`; `displayMetaStealthAddress` is that package's `metaStealthAddressUri` under its local name. The encoding itself — and the validation behind it — lives in that package. The frozen conformance vectors in `tests/vectors/registration-vectors.json` pinned the encoding across that swap: every vector value is unchanged, which is what proves the change was byte-for-byte (only the `scheme.algorithm` description has been reworded since):
+
+```
+yarn tsx packages/user-client/tests/generate-vectors.ts
+git diff --exit-code packages/user-client/tests/vectors/registration-vectors.json
+```
+
+## Dependency-injection seams: `RegistryReader` / `RegistrationSubmitter`
+
+`verifyRegistrationRequest` takes the domain you expect as its second argument. A request carries its own `chainId` and `verifyingContract`, and neither is covered by the signature, so verifying against the request's own domain would only prove it is self-consistent — a signature made for another chain or another registry would pass. Pass the domain your registry is deployed at.
+
+**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`.
+
+### 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:
+
+```typescript
+import { createHttpRegistrationSubmitter } from "@coordination-network/user-client"
+
+const submitter = createHttpRegistrationSubmitter({ url: "https://member.example" })
+const result = await register({ deviceSecret, registry, submitter, domain })
+```
+
+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.
+
+## 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.
+- **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.
+
+## Integration test
+
+`tests/integration` spawns `anvil`, deploys `SemaphoreVerifier`, `Semaphore`, and `IdentityRegistry` from the forge artifacts, and runs `register()` against the real contract with `IdentityRegistryClient` as the reader. It needs `anvil` on `PATH` and `yarn build:contracts` beforehand, and runs as part of `yarn test`; without `anvil` it is skipped locally and fails in CI.
+
+## License
+
+MIT, see [`LICENSE`](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,446 @@
+'use strict';
+
+var identity = require('@coordination-network/identity');
+var sha3 = require('@noble/hashes/sha3');
+var utils = require('@noble/hashes/utils');
+var secp256k1 = require('@noble/curves/secp256k1');
+
+/** Base error class for all errors thrown by this package, discriminated by `code`. */
+class UserClientError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "UserClientError";
+        this.code = code;
+    }
+}
+class SubmissionFailedError extends UserClientError {
+    constructor(message, cause) {
+        super("SUBMISSION_FAILED", message);
+        this.name = "SubmissionFailedError";
+        if (cause !== undefined) {
+            // Non-enumerable, matching the standard Error.cause. Provider errors hold circular
+            // transport graphs, so an enumerable copy makes JSON.stringify throw inside a
+            // caller's error handler and drags the provider's URL into its logs.
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
+        }
+    }
+}
+class RegistryReadFailedError extends UserClientError {
+    constructor(message, cause) {
+        super("REGISTRY_READ_FAILED", message);
+        this.name = "RegistryReadFailedError";
+        if (cause !== undefined) {
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
+        }
+    }
+}
+
+/** ERC-6538 scheme 1 (secp256k1 stealth addresses), the schemeId field of the consent struct. */
+const SCHEME_ID = 1;
+/** networkId is a bytes32 on chain, and abi.encode splices it in as one word. */
+const NETWORK_ID_LENGTH = 32;
+/** r || s || v, the 65-byte Ethereum signature layout. */
+const SIGNATURE_LENGTH = 65;
+/** keccak256 output, the only thing this package will sign. */
+const DIGEST_LENGTH = 32;
+/** Ethereum transaction hash, as HttpSubmissionError's 201 branch expects it. */
+const TX_HASH_LENGTH = 32;
+/** Wire-format version of RegistrationRequest. */
+const REQUEST_VERSION = "v1";
+const IDENTITY_REGISTRY_DOMAIN_NAME = "IdentityRegistry";
+const IDENTITY_REGISTRY_DOMAIN_VERSION = "1";
+/** Signed by the user as consent to register; the member server verifies it, the contract never reads it. */
+const REGISTER_IDENTITY_TYPE = "RegisterIdentity(bytes32 networkId,uint256 schemeId,bytes metaStealthAddress)";
+const EIP712_DOMAIN_TYPE = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)";
+
+/** Encodes a device's spending and viewing keys as its ERC-6538 scheme-1 meta-stealth address. */
+function metaStealthAddressFromKeys(keys) {
+    return identity.encodeMetaStealthAddress({
+        spendingPublicKey: keys.spending.publicKey,
+        viewingPublicKey: keys.viewing.publicKey
+    });
+}
+
+/** Parses a 0x-prefixed hex string into bytes. Throws on missing prefix, odd length, or non-hex chars. */
+function hexToBytes(hex) {
+    if (typeof hex !== "string" || !hex.startsWith("0x")) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 0x-prefixed hex string, got ${typeof hex}`);
+    }
+    const body = hex.slice(2);
+    if (body.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(body)) {
+        throw new UserClientError("INVALID_INPUT", `Malformed hex string of length ${body.length}`);
+    }
+    return utils.hexToBytes(body);
+}
+function bytesToHex(bytes) {
+    return `0x${utils.bytesToHex(bytes)}`;
+}
+function concatBytes(...arrays) {
+    return utils.concatBytes(...arrays);
+}
+/** Big-endian 32-byte word encoding of a non-negative safe-integer uint256, as abi.encode would produce. */
+function numberToWord(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new UserClientError("INVALID_INPUT", `Expected a non-negative safe integer, got ${typeof value} ${value}`);
+    }
+    const word = new Uint8Array(32);
+    let remaining = BigInt(value);
+    for (let i = 31; i >= 0 && remaining > 0n; i -= 1) {
+        word[i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return word;
+}
+/** Left-pads a 20-byte address into a 32-byte word, as abi.encode would produce. */
+function addressToWord(address) {
+    const addressBytes = hexToBytes(address);
+    if (addressBytes.length !== 20) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 20-byte address, got ${addressBytes.length} bytes`);
+    }
+    const word = new Uint8Array(32);
+    word.set(addressBytes, 12);
+    return word;
+}
+
+const EIP712_DOMAIN_TYPEHASH = sha3.keccak_256(utils.utf8ToBytes(EIP712_DOMAIN_TYPE));
+const REGISTER_IDENTITY_TYPEHASH = sha3.keccak_256(utils.utf8ToBytes(REGISTER_IDENTITY_TYPE));
+/** Every input is already a 32-byte word, so concatenating them is what abi.encode would emit. */
+function hashEncodedWords(...words) {
+    return sha3.keccak_256(concatBytes(...words));
+}
+function identityRegistryDomainSeparator(domain) {
+    const nameHash = sha3.keccak_256(utils.utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_NAME));
+    const versionHash = sha3.keccak_256(utils.utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_VERSION));
+    return bytesToHex(hashEncodedWords(EIP712_DOMAIN_TYPEHASH, nameHash, versionHash, numberToWord(domain.chainId), addressToWord(domain.verifyingContract)));
+}
+function registerIdentityStructHash(networkId, metaStealthAddress) {
+    const networkIdWord = hexToBytes(networkId);
+    if (networkIdWord.length !== NETWORK_ID_LENGTH) {
+        throw new UserClientError("INVALID_INPUT", `Expected a ${NETWORK_ID_LENGTH}-byte networkId, got ${networkIdWord.length} bytes`);
+    }
+    const metaHash = sha3.keccak_256(hexToBytes(metaStealthAddress));
+    return bytesToHex(hashEncodedWords(REGISTER_IDENTITY_TYPEHASH, networkIdWord, numberToWord(SCHEME_ID), metaHash));
+}
+/**
+ * The digest the user signs as consent to register this meta-stealth address at this registry on
+ * this chain. The member server verifies it before submitting; the contract never reads it.
+ */
+function registerIdentityDigest(domain, networkId, metaStealthAddress) {
+    const domainSeparator = hexToBytes(identityRegistryDomainSeparator(domain));
+    const structHash = hexToBytes(registerIdentityStructHash(networkId, metaStealthAddress));
+    return bytesToHex(sha3.keccak_256(concatBytes(Uint8Array.from([0x19, 0x01]), domainSeparator, structHash)));
+}
+
+/** Returns a 65-byte `r || s || v` signature, with `v = 27 + recovery id` as the contract expects. */
+function signRegisterIdentity(accountPrivateKey, digest) {
+    const digestBytes = hexToBytes(digest);
+    if (digestBytes.length !== DIGEST_LENGTH) {
+        // Exported, so refuse to sign anything that is not a digest this package produced.
+        throw new UserClientError("INVALID_INPUT", `Expected a ${DIGEST_LENGTH}-byte digest, got ${digestBytes.length}`);
+    }
+    const signature = secp256k1.secp256k1.sign(digestBytes, hexToBytes(accountPrivateKey), { lowS: true });
+    return bytesToHex(concatBytes(signature.toCompactRawBytes(), Uint8Array.from([27 + signature.recovery])));
+}
+function buildRegistrationRequest(keys, domain) {
+    const metaStealthAddress = metaStealthAddressFromKeys(keys);
+    const digest = registerIdentityDigest(domain, keys.networkId, metaStealthAddress);
+    return {
+        version: REQUEST_VERSION,
+        networkId: keys.networkId,
+        schemeId: SCHEME_ID,
+        metaStealthAddress,
+        chainId: domain.chainId,
+        verifyingContract: domain.verifyingContract,
+        signature: signRegisterIdentity(keys.account.privateKey, digest)
+    };
+}
+/**
+ * Whether a member server pinned to `expected` should accept the request: field widths, a
+ * well-formed meta-stealth address, the domain, and a signer matching the full `networkId`.
+ *
+ * `expected` is required because the domain inside a request is attacker-controlled — verifying
+ * against it would only prove the request is self-consistent, not that it targets this registry.
+ *
+ * Returns false rather than throwing, so an untrusted request can be passed in as-is.
+ */
+function verifyRegistrationRequest(request, expected) {
+    try {
+        if (request.version !== REQUEST_VERSION || request.schemeId !== SCHEME_ID)
+            return false;
+        // Neither field is covered by the signature, so both have to be pinned to the caller's own
+        // registry. Otherwise a signature made for another chain or contract replays here.
+        if (request.chainId !== expected.chainId)
+            return false;
+        if (request.verifyingContract.toLowerCase() !== expected.verifyingContract.toLowerCase())
+            return false;
+        // The contract types these as bytes32 and a 66-byte bytes. A request signed self-consistently
+        // over the wrong width verifies against itself but cannot be submitted.
+        const networkIdBytes = hexToBytes(request.networkId);
+        if (networkIdBytes.length !== NETWORK_ID_LENGTH)
+            return false;
+        if (hexToBytes(request.metaStealthAddress).length !== identity.META_STEALTH_ADDRESS_LENGTH)
+            return false;
+        // Width alone admits 66 bytes the contract would store but no one could ever pay to.
+        if (!identity.validateMetaStealthAddress(request.metaStealthAddress))
+            return false;
+        const signatureBytes = hexToBytes(request.signature);
+        if (signatureBytes.length !== SIGNATURE_LENGTH)
+            return false;
+        const rs = signatureBytes.slice(0, 64);
+        const recovery = signatureBytes[64] - 27;
+        if (recovery !== 0 && recovery !== 1)
+            return false;
+        const digest = registerIdentityDigest(expected, request.networkId, request.metaStealthAddress);
+        const signature = secp256k1.secp256k1.Signature.fromCompact(rs).addRecoveryBit(recovery);
+        // Signing uses `lowS` (EIP-2), so verification rejects high-S to agree with it.
+        if (signature.hasHighS())
+            return false;
+        const recoveredPublicKey = signature.recoverPublicKey(hexToBytes(digest)).toBytes(false);
+        // computeNetworkId is keccak256(X || Y); compare all 32 bytes. An address-style check over the
+        // low 20 would leave the top 12 unauthenticated and let one key claim 2^96 ids. The contract
+        // itself checks no signer at all.
+        return identity.computeNetworkId(recoveredPublicKey).toLowerCase() === request.networkId.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * In-memory stand-in for the registry's read model and the two reverts on its register path,
+ * length then duplicate; updateIdentity/removeIdentity are not modelled. `tests/integration`
+ * asserts both reverts against the real contract and this fake side by side.
+ */
+class InMemoryIdentityRegistry {
+    constructor() {
+        this.identities = new Map();
+    }
+    registerIdentity(networkId, metaStealthAddress) {
+        const length = hexToBytes(metaStealthAddress).length;
+        if (length !== identity.META_STEALTH_ADDRESS_LENGTH) {
+            throw new SubmissionFailedError(`InvalidMetaStealthAddressLength: expected ${identity.META_STEALTH_ADDRESS_LENGTH} bytes, got ${length}`);
+        }
+        const key = networkId.toLowerCase();
+        if (this.identities.has(key)) {
+            throw new SubmissionFailedError(`AlreadyRegistered: ${networkId}`);
+        }
+        this.identities.set(key, metaStealthAddress);
+    }
+    async getIdentity(networkId) {
+        return this.identities.get(networkId.toLowerCase()) ?? null;
+    }
+}
+
+/**
+ * Stands in for an approved network member's server: checks the user's consent the way a real
+ * server must before writing, then writes. The Semaphore proof a real server builds before
+ * submitting on chain is implied by construction, not modeled here.
+ */
+class InMemoryMemberServer {
+    constructor(registry, domain) {
+        this.registry = registry;
+        this.domain = domain;
+    }
+    async submit(request) {
+        if (!verifyRegistrationRequest(request, this.domain)) {
+            throw new SubmissionFailedError("InvalidRegistrationRequest");
+        }
+        this.registry.registerIdentity(request.networkId, request.metaStealthAddress);
+        return { txHash: bytesToHex(sha3.keccak_256(hexToBytes(request.signature))) };
+    }
+}
+
+function onboard(deviceSecret) {
+    const keys = identity.deriveKeys(deviceSecret);
+    const metaStealthAddress = metaStealthAddressFromKeys(keys);
+    return {
+        keys,
+        networkId: keys.networkId,
+        metaStealthAddress,
+        displayMetaStealthAddress: identity.metaStealthAddressUri(metaStealthAddress)
+    };
+}
+/**
+ * IdentityRegistry stores the mapping as `bytes`, so its generated getter answers an unregistered
+ * networkId with empty bytes. A reader built straight onto viem or ethers therefore returns "0x"
+ * where this package's port requires null, and treating that as an entry would report success while
+ * never registering anything.
+ */
+function readExistingEntry(value, networkId) {
+    if (value === null || value === "0x")
+        return null;
+    const length = hexToBytes(value).length;
+    if (length !== identity.META_STEALTH_ADDRESS_LENGTH) {
+        throw new UserClientError("INVALID_INPUT", `RegistryReader returned a ${length}-byte entry for ${networkId}; expected ${identity.META_STEALTH_ADDRESS_LENGTH} bytes or null`);
+    }
+    return value;
+}
+async function register(params) {
+    const { keys, networkId, metaStealthAddress } = onboard(params.deviceSecret);
+    let existingRaw;
+    try {
+        existingRaw = await params.registry.getIdentity(networkId);
+    }
+    catch (error) {
+        throw new RegistryReadFailedError(`registry read failed for ${networkId}`, error);
+    }
+    const existing = readExistingEntry(existingRaw, networkId);
+    if (existing !== null) {
+        // A mismatch means this device's keys do not derive the address its networkId currently
+        // resolves to. Only a network member calling updateIdentity can change that entry.
+        return {
+            status: "alreadyRegistered",
+            networkId,
+            metaStealthAddress: existing,
+            derivedMetaStealthAddress: metaStealthAddress,
+            matchesDerived: existing.toLowerCase() === metaStealthAddress.toLowerCase()
+        };
+    }
+    const request = buildRegistrationRequest(keys, params.domain);
+    let receipt;
+    try {
+        receipt = await params.submitter.submit(request);
+    }
+    catch (error) {
+        if (error instanceof SubmissionFailedError)
+            throw error;
+        throw new SubmissionFailedError(`Registration submission failed for ${networkId}`, error);
+    }
+    return { status: "registered", networkId, metaStealthAddress, request, receipt };
+}
+
+/**
+ * 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`.
+ */
+class HttpSubmissionError extends SubmissionFailedError {
+    constructor(message, init) {
+        super(message, init.cause);
+        this.name = "HttpSubmissionError";
+        this.status = init.status;
+        this.reason = init.reason;
+        this.serverCode = init.serverCode;
+        this.metaStealthAddress = init.metaStealthAddress;
+        this.matchesRequest = init.matchesRequest;
+    }
+}
+/** Parses `value` as a 32-byte `0x` hex tx hash, or `null` if it isn't one. */
+function parseTxHash(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        return hexToBytes(value).length === TX_HASH_LENGTH ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
+    return {
+        async submit(request) {
+            let response;
+            try {
+                response = await fetchImpl(`${url}/v1/registrations`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(request)
+                });
+            }
+            catch (error) {
+                throw new HttpSubmissionError("Registration submission failed: network error", {
+                    reason: "network",
+                    cause: error
+                });
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch (error) {
+                throw new HttpSubmissionError(`Registration submission returned ${response.status} with no JSON body`, {
+                    status: response.status,
+                    reason: "invalidResponse",
+                    cause: error
+                });
+            }
+            if (response.status === 201) {
+                const txHash = parseTxHash(body?.txHash);
+                if (txHash === null) {
+                    throw new HttpSubmissionError("Registration submission returned 201 with a malformed body", {
+                        status: 201,
+                        reason: "invalidResponse"
+                    });
+                }
+                return { txHash };
+            }
+            if (response.status === 200) {
+                const { metaStealthAddress, matchesRequest } = (body ?? {});
+                throw new HttpSubmissionError("Registration already exists for this networkId", {
+                    status: 200,
+                    reason: "alreadyRegistered",
+                    metaStealthAddress,
+                    matchesRequest
+                });
+            }
+            if (response.status === 400) {
+                throw new HttpSubmissionError("Registration submission was rejected", {
+                    status: 400,
+                    reason: "rejected"
+                });
+            }
+            if (response.status === 503) {
+                throw new HttpSubmissionError("Registration service is unavailable", {
+                    status: 503,
+                    reason: "unavailable",
+                    serverCode: body?.code
+                });
+            }
+            throw new HttpSubmissionError(`Registration submission returned unexpected status ${response.status}`, {
+                status: response.status,
+                reason: "invalidResponse"
+            });
+        }
+    };
+}
+
+Object.defineProperty(exports, "InvalidMetaStealthAddressError", {
+    enumerable: true,
+    get: function () { return identity.InvalidMetaStealthAddressError; }
+});
+Object.defineProperty(exports, "displayMetaStealthAddress", {
+    enumerable: true,
+    get: function () { return identity.metaStealthAddressUri; }
+});
+exports.DIGEST_LENGTH = DIGEST_LENGTH;
+exports.EIP712_DOMAIN_TYPE = EIP712_DOMAIN_TYPE;
+exports.HttpSubmissionError = HttpSubmissionError;
+exports.IDENTITY_REGISTRY_DOMAIN_NAME = IDENTITY_REGISTRY_DOMAIN_NAME;
+exports.IDENTITY_REGISTRY_DOMAIN_VERSION = IDENTITY_REGISTRY_DOMAIN_VERSION;
+exports.InMemoryIdentityRegistry = InMemoryIdentityRegistry;
+exports.InMemoryMemberServer = InMemoryMemberServer;
+exports.NETWORK_ID_LENGTH = NETWORK_ID_LENGTH;
+exports.REGISTER_IDENTITY_TYPE = REGISTER_IDENTITY_TYPE;
+exports.REQUEST_VERSION = REQUEST_VERSION;
+exports.RegistryReadFailedError = RegistryReadFailedError;
+exports.SCHEME_ID = SCHEME_ID;
+exports.SIGNATURE_LENGTH = SIGNATURE_LENGTH;
+exports.SubmissionFailedError = SubmissionFailedError;
+exports.TX_HASH_LENGTH = TX_HASH_LENGTH;
+exports.UserClientError = UserClientError;
+exports.buildRegistrationRequest = buildRegistrationRequest;
+exports.createHttpRegistrationSubmitter = createHttpRegistrationSubmitter;
+exports.identityRegistryDomainSeparator = identityRegistryDomainSeparator;
+exports.metaStealthAddressFromKeys = metaStealthAddressFromKeys;
+exports.onboard = onboard;
+exports.register = register;
+exports.registerIdentityDigest = registerIdentityDigest;
+exports.registerIdentityStructHash = registerIdentityStructHash;
+exports.signRegisterIdentity = signRegisterIdentity;
+exports.verifyRegistrationRequest = verifyRegistrationRequest;