@coordination-network/user-client 0.0.1

package/src/http-submitter.ts

@@ -0,0 +1,151 @@
+import { Hex, RegistrationRequest, RegistrationSubmitter, SubmissionReceipt } from "./types"
+import { hexToBytes } from "./bytes"
+import { TX_HASH_LENGTH } from "./constants"
+import { SubmissionFailedError } from "./errors"
+
+export type HttpSubmissionReason = "alreadyRegistered" | "rejected" | "unavailable" | "network" | "invalidResponse"
+
+export interface HttpSubmissionErrorInit {
+    status?: number
+    reason: HttpSubmissionReason
+    /** The server's own error code, where the response body carried one. */
+    serverCode?: string
+    /** The registry's current entry, on an `alreadyRegistered` response. */
+    metaStealthAddress?: Hex
+    matchesRequest?: boolean
+    cause?: unknown
+}
+
+/**
+ * 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`.
+ */
+export class HttpSubmissionError extends SubmissionFailedError {
+    readonly status?: number
+    readonly reason: HttpSubmissionReason
+    readonly serverCode?: string
+    readonly metaStealthAddress?: Hex
+    readonly matchesRequest?: boolean
+
+    constructor(message: string, init: HttpSubmissionErrorInit) {
+        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
+    }
+}
+
+export interface HttpRegistrationSubmitterOptions {
+    url: string
+    fetch?: typeof fetch
+}
+
+interface SubmittedBody {
+    status: "submitted"
+    txHash?: unknown
+}
+
+interface AlreadyRegisteredBody {
+    status: "alreadyRegistered"
+    metaStealthAddress?: Hex
+    matchesRequest?: boolean
+}
+
+interface ErrorBody {
+    code?: string
+}
+
+/** Parses `value` as a 32-byte `0x` hex tx hash, or `null` if it isn't one. */
+function parseTxHash(value: unknown): Hex | null {
+    if (typeof value !== "string") return null
+    try {
+        return hexToBytes(value as Hex).length === TX_HASH_LENGTH ? (value as Hex) : 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.
+ */
+export function createHttpRegistrationSubmitter({
+    url,
+    fetch: fetchImpl = fetch
+}: HttpRegistrationSubmitterOptions): RegistrationSubmitter {
+    return {
+        async submit(request: RegistrationRequest): Promise<SubmissionReceipt> {
+            let response: 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: unknown
+            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 as SubmittedBody | null)?.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 ?? {}) as AlreadyRegisteredBody
+                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 as ErrorBody | null)?.code
+                })
+            }
+
+            throw new HttpSubmissionError(`Registration submission returned unexpected status ${response.status}`, {
+                status: response.status,
+                reason: "invalidResponse"
+            })
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export type { DerivedKeys } from "@coordination-network/identity"
+export { InvalidMetaStealthAddressError } from "@coordination-network/identity"
+
+export * from "./errors"
+export * from "./types"
+export * from "./constants"
+export * from "./meta"
+export * from "./eip712"
+export * from "./request"
+export * from "./registry"
+export * from "./member-server"
+export * from "./register"
+export * from "./http-submitter"

package/src/member-server.ts

@@ -0,0 +1,26 @@
+import { keccak_256 } from "@noble/hashes/sha3"
+import { ChainDomain, RegistrationRequest, RegistrationSubmitter, SubmissionReceipt } from "./types"
+import { hexToBytes, bytesToHex } from "./bytes"
+import { verifyRegistrationRequest } from "./request"
+import { SubmissionFailedError } from "./errors"
+import { InMemoryIdentityRegistry } from "./registry"
+
+/**
+ * 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.
+ */
+export class InMemoryMemberServer implements RegistrationSubmitter {
+    constructor(
+        private readonly registry: InMemoryIdentityRegistry,
+        private readonly domain: ChainDomain
+    ) {}
+
+    async submit(request: RegistrationRequest): Promise<SubmissionReceipt> {
+        if (!verifyRegistrationRequest(request, this.domain)) {
+            throw new SubmissionFailedError("InvalidRegistrationRequest")
+        }
+        this.registry.registerIdentity(request.networkId, request.metaStealthAddress)
+        return { txHash: bytesToHex(keccak_256(hexToBytes(request.signature))) }
+    }
+}

package/src/meta.ts

@@ -0,0 +1,13 @@
+import { DerivedKeys, encodeMetaStealthAddress } from "@coordination-network/identity"
+import { Hex } from "./types"
+
+/** Encodes a device's spending and viewing keys as its ERC-6538 scheme-1 meta-stealth address. */
+export function metaStealthAddressFromKeys(keys: DerivedKeys): Hex {
+    return encodeMetaStealthAddress({
+        spendingPublicKey: keys.spending.publicKey,
+        viewingPublicKey: keys.viewing.publicKey
+    })
+}
+
+/** Aliased, not reimplemented, so the `st:eth:` prefix lives in one place. */
+export { metaStealthAddressUri as displayMetaStealthAddress } from "@coordination-network/identity"

package/src/register.ts

@@ -0,0 +1,70 @@
+import { deriveKeys, META_STEALTH_ADDRESS_LENGTH } from "@coordination-network/identity"
+import { Hex, Onboarding, RegisterParams, RegisterResult } from "./types"
+import { metaStealthAddressFromKeys, displayMetaStealthAddress } from "./meta"
+import { buildRegistrationRequest } from "./request"
+import { hexToBytes } from "./bytes"
+import { RegistryReadFailedError, SubmissionFailedError, UserClientError } from "./errors"
+
+export function onboard(deviceSecret: Uint8Array | Hex): Onboarding {
+    const keys = deriveKeys(deviceSecret)
+    const metaStealthAddress = metaStealthAddressFromKeys(keys)
+    return {
+        keys,
+        networkId: keys.networkId,
+        metaStealthAddress,
+        displayMetaStealthAddress: displayMetaStealthAddress(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: Hex | null, networkId: Hex): Hex | null {
+    if (value === null || value === "0x") return null
+
+    const length = hexToBytes(value).length
+    if (length !== META_STEALTH_ADDRESS_LENGTH) {
+        throw new UserClientError(
+            "INVALID_INPUT",
+            `RegistryReader returned a ${length}-byte entry for ${networkId}; expected ${META_STEALTH_ADDRESS_LENGTH} bytes or null`
+        )
+    }
+    return value
+}
+
+export async function register(params: RegisterParams): Promise<RegisterResult> {
+    const { keys, networkId, metaStealthAddress } = onboard(params.deviceSecret)
+
+    let existingRaw: Hex | null
+    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 }
+}

package/src/registry.ts

@@ -0,0 +1,32 @@
+import { META_STEALTH_ADDRESS_LENGTH } from "@coordination-network/identity"
+import { Hex, RegistryReader } from "./types"
+import { hexToBytes } from "./bytes"
+import { SubmissionFailedError } from "./errors"
+
+/**
+ * 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.
+ */
+export class InMemoryIdentityRegistry implements RegistryReader {
+    private readonly identities = new Map<Hex, Hex>()
+
+    registerIdentity(networkId: Hex, metaStealthAddress: Hex): void {
+        const length = hexToBytes(metaStealthAddress).length
+        if (length !== META_STEALTH_ADDRESS_LENGTH) {
+            throw new SubmissionFailedError(
+                `InvalidMetaStealthAddressLength: expected ${META_STEALTH_ADDRESS_LENGTH} bytes, got ${length}`
+            )
+        }
+
+        const key = networkId.toLowerCase() as Hex
+        if (this.identities.has(key)) {
+            throw new SubmissionFailedError(`AlreadyRegistered: ${networkId}`)
+        }
+        this.identities.set(key, metaStealthAddress)
+    }
+
+    async getIdentity(networkId: Hex): Promise<Hex | null> {
+        return this.identities.get(networkId.toLowerCase() as Hex) ?? null
+    }
+}

package/src/request.ts

@@ -0,0 +1,89 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import {
+    computeNetworkId,
+    DerivedKeys,
+    META_STEALTH_ADDRESS_LENGTH,
+    validateMetaStealthAddress
+} from "@coordination-network/identity"
+import { ChainDomain, Hex, RegistrationRequest } from "./types"
+import { hexToBytes, bytesToHex, concatBytes } from "./bytes"
+import { UserClientError } from "./errors"
+import { registerIdentityDigest } from "./eip712"
+import { metaStealthAddressFromKeys } from "./meta"
+import { DIGEST_LENGTH, NETWORK_ID_LENGTH, REQUEST_VERSION, SCHEME_ID, SIGNATURE_LENGTH } from "./constants"
+
+/** Returns a 65-byte `r || s || v` signature, with `v = 27 + recovery id` as the contract expects. */
+export function signRegisterIdentity(accountPrivateKey: Hex, digest: Hex): Hex {
+    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.sign(digestBytes, hexToBytes(accountPrivateKey), { lowS: true })
+    return bytesToHex(concatBytes(signature.toCompactRawBytes(), Uint8Array.from([27 + signature.recovery])))
+}
+
+export function buildRegistrationRequest(keys: DerivedKeys, domain: ChainDomain): RegistrationRequest {
+    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.
+ */
+export function verifyRegistrationRequest(request: RegistrationRequest, expected: ChainDomain): boolean {
+    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 !== META_STEALTH_ADDRESS_LENGTH) return false
+
+        // Width alone admits 66 bytes the contract would store but no one could ever pay to.
+        if (!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.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 computeNetworkId(recoveredPublicKey).toLowerCase() === request.networkId.toLowerCase()
+    } catch {
+        return false
+    }
+}

package/src/types.ts

@@ -0,0 +1,71 @@
+import { DerivedKeys } from "@coordination-network/identity"
+
+export type Hex = `0x${string}`
+
+/** The registry deployment the consent is bound to. */
+export interface ChainDomain {
+    chainId: number
+    verifyingContract: Hex
+}
+
+export interface RegistrationRequest {
+    version: "v1"
+    networkId: Hex
+    schemeId: 1
+    metaStealthAddress: Hex
+    chainId: number
+    verifyingContract: Hex
+    /** EIP-712 consent over the request, checked by the member server. */
+    signature: Hex
+}
+
+export interface SubmissionReceipt {
+    /** Null when the submitter queued the registration rather than broadcasting it itself. */
+    txHash: Hex | null
+}
+
+export interface RegistryReader {
+    /**
+     * The 66-byte entry, or null when the networkId is unregistered. IdentityRegistry stores the
+     * mapping as `bytes`, so a chain-backed reader must map its empty-bytes answer to null.
+     */
+    getIdentity(networkId: Hex): Promise<Hex | null>
+}
+
+/** Hands the signed request to the network member's server, which submits it on chain. */
+export interface RegistrationSubmitter {
+    submit(request: RegistrationRequest): Promise<SubmissionReceipt>
+}
+
+export interface Onboarding {
+    keys: DerivedKeys
+    networkId: Hex
+    metaStealthAddress: Hex
+    displayMetaStealthAddress: string
+}
+
+export interface RegisterParams {
+    deviceSecret: Uint8Array | Hex
+    registry: RegistryReader
+    submitter: RegistrationSubmitter
+    domain: ChainDomain
+}
+
+export type RegisterResult =
+    | {
+          /** Submitted, not confirmed: `register` returns as soon as the submitter accepts. */
+          status: "registered"
+          networkId: Hex
+          metaStealthAddress: Hex
+          request: RegistrationRequest
+          receipt: SubmissionReceipt
+      }
+    | {
+          status: "alreadyRegistered"
+          networkId: Hex
+          /** What the registry currently resolves to; a network member can change it via updateIdentity/removeIdentity. */
+          metaStealthAddress: Hex
+          /** What this device secret derives today. */
+          derivedMetaStealthAddress: Hex
+          matchesDerived: boolean
+      }

package/types/index.d.ts

@@ -0,0 +1,185 @@
+import { DerivedKeys } from '@coordination-network/identity';
+export { DerivedKeys, InvalidMetaStealthAddressError, metaStealthAddressUri as displayMetaStealthAddress } from '@coordination-network/identity';
+
+type UserClientErrorCode = "INVALID_INPUT" | "SUBMISSION_FAILED" | "REGISTRY_READ_FAILED";
+/** Base error class for all errors thrown by this package, discriminated by `code`. */
+declare class UserClientError extends Error {
+    readonly code: UserClientErrorCode;
+    constructor(code: UserClientErrorCode, message: string);
+}
+declare class SubmissionFailedError extends UserClientError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare class RegistryReadFailedError extends UserClientError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+type Hex = `0x${string}`;
+/** The registry deployment the consent is bound to. */
+interface ChainDomain {
+    chainId: number;
+    verifyingContract: Hex;
+}
+interface RegistrationRequest {
+    version: "v1";
+    networkId: Hex;
+    schemeId: 1;
+    metaStealthAddress: Hex;
+    chainId: number;
+    verifyingContract: Hex;
+    /** EIP-712 consent over the request, checked by the member server. */
+    signature: Hex;
+}
+interface SubmissionReceipt {
+    /** Null when the submitter queued the registration rather than broadcasting it itself. */
+    txHash: Hex | null;
+}
+interface RegistryReader {
+    /**
+     * The 66-byte entry, or null when the networkId is unregistered. IdentityRegistry stores the
+     * mapping as `bytes`, so a chain-backed reader must map its empty-bytes answer to null.
+     */
+    getIdentity(networkId: Hex): Promise<Hex | null>;
+}
+/** Hands the signed request to the network member's server, which submits it on chain. */
+interface RegistrationSubmitter {
+    submit(request: RegistrationRequest): Promise<SubmissionReceipt>;
+}
+interface Onboarding {
+    keys: DerivedKeys;
+    networkId: Hex;
+    metaStealthAddress: Hex;
+    displayMetaStealthAddress: string;
+}
+interface RegisterParams {
+    deviceSecret: Uint8Array | Hex;
+    registry: RegistryReader;
+    submitter: RegistrationSubmitter;
+    domain: ChainDomain;
+}
+type RegisterResult = {
+    /** Submitted, not confirmed: `register` returns as soon as the submitter accepts. */
+    status: "registered";
+    networkId: Hex;
+    metaStealthAddress: Hex;
+    request: RegistrationRequest;
+    receipt: SubmissionReceipt;
+} | {
+    status: "alreadyRegistered";
+    networkId: Hex;
+    /** What the registry currently resolves to; a network member can change it via updateIdentity/removeIdentity. */
+    metaStealthAddress: Hex;
+    /** What this device secret derives today. */
+    derivedMetaStealthAddress: Hex;
+    matchesDerived: boolean;
+};
+
+/** ERC-6538 scheme 1 (secp256k1 stealth addresses), the schemeId field of the consent struct. */
+declare const SCHEME_ID: 1;
+/** networkId is a bytes32 on chain, and abi.encode splices it in as one word. */
+declare const NETWORK_ID_LENGTH = 32;
+/** r || s || v, the 65-byte Ethereum signature layout. */
+declare const SIGNATURE_LENGTH = 65;
+/** keccak256 output, the only thing this package will sign. */
+declare const DIGEST_LENGTH = 32;
+/** Ethereum transaction hash, as HttpSubmissionError's 201 branch expects it. */
+declare const TX_HASH_LENGTH = 32;
+/** Wire-format version of RegistrationRequest. */
+declare const REQUEST_VERSION: "v1";
+declare const IDENTITY_REGISTRY_DOMAIN_NAME = "IdentityRegistry";
+declare const IDENTITY_REGISTRY_DOMAIN_VERSION = "1";
+/** Signed by the user as consent to register; the member server verifies it, the contract never reads it. */
+declare const REGISTER_IDENTITY_TYPE = "RegisterIdentity(bytes32 networkId,uint256 schemeId,bytes metaStealthAddress)";
+declare 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. */
+declare function metaStealthAddressFromKeys(keys: DerivedKeys): Hex;
+
+declare function identityRegistryDomainSeparator(domain: ChainDomain): Hex;
+declare function registerIdentityStructHash(networkId: Hex, metaStealthAddress: Hex): Hex;
+/**
+ * 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.
+ */
+declare function registerIdentityDigest(domain: ChainDomain, networkId: Hex, metaStealthAddress: Hex): Hex;
+
+/** Returns a 65-byte `r || s || v` signature, with `v = 27 + recovery id` as the contract expects. */
+declare function signRegisterIdentity(accountPrivateKey: Hex, digest: Hex): Hex;
+declare function buildRegistrationRequest(keys: DerivedKeys, domain: ChainDomain): RegistrationRequest;
+/**
+ * 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.
+ */
+declare function verifyRegistrationRequest(request: RegistrationRequest, expected: ChainDomain): boolean;
+
+/**
+ * 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.
+ */
+declare class InMemoryIdentityRegistry implements RegistryReader {
+    private readonly identities;
+    registerIdentity(networkId: Hex, metaStealthAddress: Hex): void;
+    getIdentity(networkId: Hex): Promise<Hex | 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.
+ */
+declare class InMemoryMemberServer implements RegistrationSubmitter {
+    private readonly registry;
+    private readonly domain;
+    constructor(registry: InMemoryIdentityRegistry, domain: ChainDomain);
+    submit(request: RegistrationRequest): Promise<SubmissionReceipt>;
+}
+
+declare function onboard(deviceSecret: Uint8Array | Hex): Onboarding;
+declare function register(params: RegisterParams): Promise<RegisterResult>;
+
+type HttpSubmissionReason = "alreadyRegistered" | "rejected" | "unavailable" | "network" | "invalidResponse";
+interface HttpSubmissionErrorInit {
+    status?: number;
+    reason: HttpSubmissionReason;
+    /** The server's own error code, where the response body carried one. */
+    serverCode?: string;
+    /** The registry's current entry, on an `alreadyRegistered` response. */
+    metaStealthAddress?: Hex;
+    matchesRequest?: boolean;
+    cause?: unknown;
+}
+/**
+ * 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`.
+ */
+declare class HttpSubmissionError extends SubmissionFailedError {
+    readonly status?: number;
+    readonly reason: HttpSubmissionReason;
+    readonly serverCode?: string;
+    readonly metaStealthAddress?: Hex;
+    readonly matchesRequest?: boolean;
+    constructor(message: string, init: HttpSubmissionErrorInit);
+}
+interface HttpRegistrationSubmitterOptions {
+    url: string;
+    fetch?: typeof fetch;
+}
+/**
+ * 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;
+
+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 };