@coordination-network/identity 0.0.1

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@coordination-network/identity",
+  "version": "0.0.1",
+  "description": "Deterministic device key derivation for the coordination network: networkId and the four-key secp256k1 model (account, spending, viewing, auth) from one device secret, plus a hardware-rooted Baby Jubjub EdDSA/Semaphore-commitment fifth key.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/identity"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/identity",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "src/",
+    "README.md",
+    "DERIVATION.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist types && rollup -c rollup.config.mjs"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@zk-kit/eddsa-poseidon": "1.0.4",
+    "poseidon-lite": "0.3.0"
+  },
+  "devDependencies": {
+    "@fluidkey/stealth-account-kit": "1.1.1",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@scopelift/stealth-address-sdk": "^1.0.0-beta.5",
+    "@semaphore-protocol/identity": "4.14.3",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/account.ts

@@ -0,0 +1,61 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import { keccak_256 } from "@noble/hashes/sha3"
+import type { Hex, Secp256k1Keypair } from "./types"
+import { DOMAIN_ACCOUNT, FIXED_DOMAIN_MSG } from "./constants"
+import { bytesToHex, concatBytes, normalizeDeviceSecret, toBytes, utf8ToBytes } from "./bytes"
+import { hashToScalar } from "./hash-to-scalar"
+import { scalarToKeypair } from "./keypair"
+
+/**
+ * Derives the root secp256k1 account keypair from a 32-byte device secret.
+ *
+ * NORMATIVE: `accountPrivKey = hashToScalar(DOMAIN_ACCOUNT, deviceSecret)`.
+ */
+export function deriveAccountKeypair(deviceSecret: Uint8Array | Hex): Secp256k1Keypair {
+    const secret = normalizeDeviceSecret(deviceSecret)
+    const scalar = hashToScalar(DOMAIN_ACCOUNT, secret)
+
+    return scalarToKeypair(scalar)
+}
+
+/**
+ * Normalizes a 64-byte compact ECDSA signature (`r || s`) to raw bytes.
+ *
+ * @internal
+ */
+export function normalizeSignature64(sig64: Uint8Array | Hex): Uint8Array {
+    const bytes = toBytes(sig64)
+
+    if (bytes.length !== 64) {
+        throw new TypeError("normalizeSignature64: expected a 64-byte compact signature (r || s)")
+    }
+
+    return bytes
+}
+
+/**
+ * EIP-191 personal-sign digest:
+ * `keccak256(utf8("\x19Ethereum Signed Message:\n" + decimalByteLength) || message)`.
+ *
+ * @internal
+ */
+export function eip191Digest(message: Uint8Array): Uint8Array {
+    const prefix = utf8ToBytes(`\x19Ethereum Signed Message:\n${String(message.length)}`)
+
+    return keccak_256(concatBytes(prefix, message))
+}
+
+/**
+ * Signs the fixed derivation message with the account private key.
+ *
+ * NORMATIVE: the EIP-191 digest of {@link FIXED_DOMAIN_MSG}, signed with
+ * RFC-6979 deterministic ECDSA (`lowS: true`, no `extraEntropy`), returned as
+ * the 64-byte compact `r || s` encoding.
+ */
+export function signDerivationMessage(accountPrivateKey: Hex | Uint8Array): Hex {
+    const privateKey = toBytes(accountPrivateKey)
+    const digest = eip191Digest(utf8ToBytes(FIXED_DOMAIN_MSG))
+    const signature = secp256k1.sign(digest, privateKey, { lowS: true })
+
+    return bytesToHex(signature.toCompactRawBytes())
+}

package/src/auth.ts

@@ -0,0 +1,20 @@
+import type { Hex, Secp256k1Keypair } from "./types"
+import { DOMAIN_AUTH } from "./constants"
+import { normalizeSignature64 } from "./account"
+import { hashToScalar } from "./hash-to-scalar"
+import { scalarToKeypair } from "./keypair"
+
+/**
+ * Derives the secp256k1 auth keypair from the 64-byte compact
+ * derivation-message signature.
+ *
+ * NORMATIVE: `authPrivKey = hashToScalar(DOMAIN_AUTH, sig64)`.
+ *
+ * `sig64` is unauthenticated — prefer {@link deriveKeys} (see `DERIVATION.md`).
+ */
+export function deriveAuthKeypair(sig64: Uint8Array | Hex): Secp256k1Keypair {
+    const signature = normalizeSignature64(sig64)
+    const scalar = hashToScalar(DOMAIN_AUTH, signature)
+
+    return scalarToKeypair(scalar)
+}

package/src/binding.ts

@@ -0,0 +1,298 @@
+/**
+ * Credential dual proof-of-possession binding — see `DERIVATION.md` §11.
+ *
+ * NORMATIVE layouts:
+ * ```
+ * deviceBindingMessage  = nonce(32) || networkId(32) || holderKeyCommitment(32) // credential issuance
+ * accountBindingMessage = nonce(32) || confirmationKeyHash(32) || networkId(32) // 96B, signed by A (secp256k1)
+ * ```
+ *
+ * NORMATIVE MUST: the device signs a locally-derived `networkId`, never one
+ * supplied by the issuance request. Every function here except the two
+ * low-level builders and {@link verifyDeviceBindingSignature} enforces this
+ * by deriving `networkId` internally rather than accepting it as a parameter.
+ */
+
+import { secp256k1 } from "@noble/curves/secp256k1"
+import { p256 } from "@noble/curves/p256"
+import type { Hex } from "./types"
+import { BINDING_NONCE_LENGTH } from "./constants"
+import { bytesToHex, concatBytes, prependUncompressedPrefix, toBytes } from "./bytes"
+import { eip191Digest, normalizeSignature64 } from "./account"
+import { computeNetworkId } from "./network-id"
+import { normalizeConfirmationKey, computeConfirmationKeyHash } from "./confirmation-key"
+import { InvalidBindingInputError } from "./errors"
+
+function toBindingBytes(value: Uint8Array | Hex, label: string): Uint8Array {
+    try {
+        return toBytes(value)
+    } catch {
+        throw new InvalidBindingInputError(`${label}: expected raw bytes or a well-formed 0x-prefixed hex string`)
+    }
+}
+
+function decodeAndValidateNonceAndNetworkId(
+    nonce: Uint8Array | Hex,
+    networkId: Uint8Array | Hex
+): { nonceBytes: Uint8Array; networkIdBytes: Uint8Array } {
+    const nonceBytes = toBindingBytes(nonce, "nonce")
+    const networkIdBytes = toBindingBytes(networkId, "networkId")
+
+    if (nonceBytes.length !== BINDING_NONCE_LENGTH) {
+        throw new InvalidBindingInputError(`nonce: expected exactly ${BINDING_NONCE_LENGTH} bytes`)
+    }
+
+    if (networkIdBytes.length !== BINDING_NONCE_LENGTH) {
+        throw new InvalidBindingInputError(`networkId: expected exactly ${BINDING_NONCE_LENGTH} bytes`)
+    }
+
+    return { nonceBytes, networkIdBytes }
+}
+
+/**
+ * Normalizes an `accountPublicKey` (65-byte uncompressed, 33-byte compressed,
+ * or 64-byte raw `X || Y`) to its 65-byte SEC1 uncompressed encoding,
+ * validating that it is on the secp256k1 curve.
+ */
+function normalizeAccountPublicKey(accountPublicKey: Uint8Array | Hex): Uint8Array {
+    const bytes = toBindingBytes(accountPublicKey, "accountPublicKey")
+
+    if (bytes.length !== 33 && bytes.length !== 64 && bytes.length !== 65) {
+        throw new InvalidBindingInputError(
+            "accountPublicKey: expected a 65-byte uncompressed, 33-byte compressed, or 64-byte raw secp256k1 public key"
+        )
+    }
+
+    const sec1Bytes = bytes.length === 64 ? prependUncompressedPrefix(bytes) : bytes
+
+    try {
+        return secp256k1.ProjectivePoint.fromHex(sec1Bytes).toRawBytes(false)
+    } catch {
+        throw new InvalidBindingInputError("accountPublicKey: not a valid on-curve secp256k1 public key")
+    }
+}
+
+function normalizeAccountSignature(signature: Uint8Array | Hex): Uint8Array {
+    try {
+        return normalizeSignature64(signature)
+    } catch {
+        throw new InvalidBindingInputError("accountSignature: expected a 64-byte compact secp256k1 signature (r || s)")
+    }
+}
+
+/**
+ * Parses a P-256 signature in either accepted platform encoding: 64-byte raw
+ * `r || s` (WebCrypto) or DER (Secure Enclave / Android Keystore). The DER
+ * `0x30` tag is checked before length because a genuine DER signature can
+ * itself be exactly 64 bytes.
+ */
+function parseDeviceSignature(signature: Uint8Array | Hex): ReturnType<typeof p256.Signature.fromCompact> {
+    const bytes = toBindingBytes(signature, "deviceSignature")
+
+    if (bytes[0] === 0x30) {
+        try {
+            return p256.Signature.fromDER(bytes)
+        } catch {
+            // not valid DER; try compact
+        }
+    }
+
+    if (bytes.length === 64) {
+        try {
+            return p256.Signature.fromCompact(bytes)
+        } catch {
+            // not valid compact either; reject below
+        }
+    }
+
+    throw new InvalidBindingInputError(
+        "deviceSignature: expected a 64-byte compact (r || s) or DER-encoded P-256 signature"
+    )
+}
+
+/**
+ * Builds `nonce(32) || networkId(32)`, optionally followed by a 32-byte holder commitment.
+ *
+ * Low-level, spec-literal builder — prefer {@link buildBindingMessages},
+ * which enforces the locally-derived-`networkId` MUST structurally.
+ */
+export function buildDeviceBindingMessage(
+    nonce: Uint8Array | Hex,
+    networkId: Uint8Array | Hex,
+    holderKeyCommitment?: Uint8Array | Hex
+): Uint8Array {
+    const { nonceBytes, networkIdBytes } = decodeAndValidateNonceAndNetworkId(nonce, networkId)
+    if (holderKeyCommitment === undefined) return concatBytes(nonceBytes, networkIdBytes)
+    const holderBytes = toBindingBytes(holderKeyCommitment, "holderKeyCommitment")
+    if (holderBytes.length !== 32) throw new InvalidBindingInputError("holderKeyCommitment: expected exactly 32 bytes")
+    return concatBytes(nonceBytes, networkIdBytes, holderBytes)
+}
+
+/**
+ * Builds the 96-byte `accountBindingMessage`:
+ * `nonce(32) || confirmationKeyHash(32) || networkId(32)`.
+ *
+ * Low-level, spec-literal builder — see {@link buildBindingMessages} for the
+ * wallet-side entry point.
+ */
+export function buildAccountBindingMessage(
+    nonce: Uint8Array | Hex,
+    confirmationKey: Uint8Array | Hex,
+    networkId: Uint8Array | Hex
+): Uint8Array {
+    const { nonceBytes, networkIdBytes } = decodeAndValidateNonceAndNetworkId(nonce, networkId)
+    const confirmationKeyHash = toBytes(computeConfirmationKeyHash(confirmationKey))
+
+    return concatBytes(nonceBytes, confirmationKeyHash, networkIdBytes)
+}
+
+/**
+ * Wallet-side entry point: builds both binding messages with `networkId`
+ * derived internally from the account's own public key, so a caller cannot
+ * supply a `networkId` from elsewhere even by mistake.
+ */
+export function buildBindingMessages(
+    nonce: Uint8Array | Hex,
+    accountUncompressedPublicKey: Uint8Array | Hex,
+    confirmationKey: Uint8Array | Hex,
+    holderKeyCommitment?: Uint8Array | Hex
+): { networkId: Hex; deviceBindingMessage: Uint8Array; accountBindingMessage: Uint8Array } {
+    let networkId: Hex
+
+    try {
+        networkId = computeNetworkId(accountUncompressedPublicKey)
+    } catch {
+        throw new InvalidBindingInputError(
+            "accountUncompressedPublicKey: expected a 65-byte 0x04-prefixed or 64-byte raw uncompressed secp256k1 public key"
+        )
+    }
+
+    const deviceBindingMessage = buildDeviceBindingMessage(nonce, networkId, holderKeyCommitment)
+    const accountBindingMessage = buildAccountBindingMessage(nonce, confirmationKey, networkId)
+
+    return { networkId, deviceBindingMessage, accountBindingMessage }
+}
+
+/**
+ * Produces `sig_A`: the EIP-191 signature over the `accountBindingMessage`,
+ * with `networkId` derived internally from the account private key. Same
+ * signing posture as {@link signDerivationMessage} (RFC-6979 deterministic,
+ * `lowS: true`, no `extraEntropy`, 64-byte compact `r || s`).
+ */
+export function signAccountBinding(
+    accountPrivateKey: Hex | Uint8Array,
+    nonce: Uint8Array | Hex,
+    confirmationKey: Uint8Array | Hex
+): { signature: Hex; networkId: Hex } {
+    const privateKeyBytes = toBytes(accountPrivateKey)
+    const uncompressedPublicKey = secp256k1.getPublicKey(privateKeyBytes, false)
+    const networkId = computeNetworkId(uncompressedPublicKey)
+
+    const message = buildAccountBindingMessage(nonce, confirmationKey, networkId)
+    const digest = eip191Digest(message)
+    const signature = secp256k1.sign(digest, privateKeyBytes, { lowS: true })
+
+    return { signature: bytesToHex(signature.toCompactRawBytes()), networkId }
+}
+
+/**
+ * Issuer-side verification of `sig_A`, with `networkId` derived internally
+ * from `accountPublicKey` — never accepted as a parameter.
+ *
+ * Malformed inputs throw {@link InvalidBindingInputError}; a well-formed
+ * signature that fails to verify returns `false`.
+ */
+export function verifyAccountBindingSignature({
+    nonce,
+    confirmationKey,
+    accountPublicKey,
+    signature
+}: {
+    nonce: Uint8Array | Hex
+    confirmationKey: Uint8Array | Hex
+    accountPublicKey: Uint8Array | Hex
+    signature: Uint8Array | Hex
+}): boolean {
+    const publicKeyBytes = normalizeAccountPublicKey(accountPublicKey)
+    const networkId = computeNetworkId(publicKeyBytes)
+
+    const message = buildAccountBindingMessage(nonce, confirmationKey, networkId)
+    const digest = eip191Digest(message)
+    const signatureBytes = normalizeAccountSignature(signature)
+
+    return secp256k1.verify(signatureBytes, digest, publicKeyBytes, { lowS: true })
+}
+
+/**
+ * Issuer-side verification of `sig_B` (hardware P-256) over the
+ * `deviceBindingMessage`. NORMATIVE MUST: `networkId` — not derivable here,
+ * since `sig_B` is independent of the account key — must be the device's
+ * locally-derived value; prefer {@link verifyCredentialBinding}.
+ *
+ * `prehash: true` (signers hash SHA-256 internally); `lowS: false` (hardware
+ * signatures aren't s-normalized — `DERIVATION.md` §11.4).
+ */
+export function verifyDeviceBindingSignature({
+    nonce,
+    networkId,
+    confirmationKey,
+    holderKeyCommitment,
+    signature
+}: {
+    nonce: Uint8Array | Hex
+    networkId: Uint8Array | Hex
+    confirmationKey: Uint8Array | Hex
+    holderKeyCommitment?: Uint8Array | Hex
+    signature: Uint8Array | Hex
+}): boolean {
+    const message = buildDeviceBindingMessage(nonce, networkId, holderKeyCommitment)
+    const publicKeyBytes = prependUncompressedPrefix(normalizeConfirmationKey(confirmationKey))
+    const parsedSignature = parseDeviceSignature(signature)
+
+    return p256.verify(parsedSignature.toCompactRawBytes(), message, publicKeyBytes, {
+        prehash: true,
+        lowS: false
+    })
+}
+
+/**
+ * The full issuer gate: one `networkId` derived from `accountPublicKey` gates
+ * both `sig_A` and `sig_B`, so a device signature from one session can't pair
+ * with an unrelated account signature in either direction. `networkId` is
+ * returned even when `valid` is false, for issuer-side logging/rate-limiting.
+ */
+export function verifyCredentialBinding({
+    nonce,
+    accountPublicKey,
+    confirmationKey,
+    holderKeyCommitment,
+    accountSignature,
+    deviceSignature
+}: {
+    nonce: Uint8Array | Hex
+    accountPublicKey: Uint8Array | Hex
+    confirmationKey: Uint8Array | Hex
+    holderKeyCommitment?: Uint8Array | Hex
+    accountSignature: Uint8Array | Hex
+    deviceSignature: Uint8Array | Hex
+}): { valid: boolean; networkId: Hex } {
+    const publicKeyBytes = normalizeAccountPublicKey(accountPublicKey)
+    const networkId = computeNetworkId(publicKeyBytes)
+
+    const accountValid = verifyAccountBindingSignature({
+        nonce,
+        confirmationKey,
+        accountPublicKey: publicKeyBytes,
+        signature: accountSignature
+    })
+
+    const deviceValid = verifyDeviceBindingSignature({
+        nonce,
+        networkId,
+        confirmationKey,
+        holderKeyCommitment,
+        signature: deviceSignature
+    })
+
+    return { valid: accountValid && deviceValid, networkId }
+}

package/src/bytes.ts

@@ -0,0 +1,142 @@
+import { bytesToHex as nobleBytesToHex, hexToBytes as nobleHexToBytes } from "@noble/hashes/utils"
+
+import type { Hex } from "./types"
+import { InvalidDeviceSecretError, InvalidEcdhSecretError } from "./errors"
+
+const HEX_RE = /^[0-9a-fA-F]*$/
+
+export { utf8ToBytes, concatBytes } from "@noble/hashes/utils"
+
+export function hexToBytes(hex: string): Uint8Array {
+    if (typeof hex !== "string" || !hex.startsWith("0x")) {
+        throw new TypeError("hexToBytes: expected a string with a 0x prefix")
+    }
+
+    const body = hex.slice(2)
+
+    if (body.length % 2 !== 0) {
+        throw new TypeError("hexToBytes: expected an even number of hex characters")
+    }
+
+    if (!HEX_RE.test(body)) {
+        throw new TypeError("hexToBytes: expected only hex characters after the 0x prefix")
+    }
+
+    return nobleHexToBytes(body)
+}
+
+export function bytesToHex(bytes: Uint8Array): Hex {
+    return `0x${nobleBytesToHex(bytes)}`
+}
+
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+
+/** Unpadded base64url (RFC 4648 §5) */
+export function bytesToBase64url(bytes: Uint8Array): string {
+    let out = ""
+    let i = 0
+
+    for (; i + 2 < bytes.length; i += 3) {
+        const chunk = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2]
+
+        out +=
+            BASE64URL_ALPHABET[(chunk >> 18) & 63] +
+            BASE64URL_ALPHABET[(chunk >> 12) & 63] +
+            BASE64URL_ALPHABET[(chunk >> 6) & 63] +
+            BASE64URL_ALPHABET[chunk & 63]
+    }
+
+    const remaining = bytes.length - i
+
+    if (remaining === 1) {
+        const chunk = bytes[i] << 16
+
+        out += BASE64URL_ALPHABET[(chunk >> 18) & 63] + BASE64URL_ALPHABET[(chunk >> 12) & 63]
+    } else if (remaining === 2) {
+        const chunk = (bytes[i] << 16) | (bytes[i + 1] << 8)
+
+        out +=
+            BASE64URL_ALPHABET[(chunk >> 18) & 63] +
+            BASE64URL_ALPHABET[(chunk >> 12) & 63] +
+            BASE64URL_ALPHABET[(chunk >> 6) & 63]
+    }
+
+    return out
+}
+
+/** Decodes unpadded base64url (RFC 4648 §5). */
+export function base64urlToBytes(encoded: string): Uint8Array {
+    if (!/^[A-Za-z0-9_-]*$/.test(encoded) || encoded.length % 4 === 1) {
+        throw new TypeError("base64urlToBytes: expected unpadded base64url")
+    }
+    const output = new Uint8Array(Math.floor((encoded.length * 6) / 8))
+    let buffer = 0
+    let bits = 0
+    let offset = 0
+    for (const character of encoded) {
+        buffer = (buffer << 6) | BASE64URL_ALPHABET.indexOf(character)
+        bits += 6
+        if (bits >= 8) {
+            bits -= 8
+            output[offset++] = (buffer >> bits) & 0xff
+            buffer &= (1 << bits) - 1
+        }
+    }
+    if (buffer !== 0) throw new TypeError("base64urlToBytes: non-canonical trailing bits")
+    return output
+}
+
+export function toBytes(value: Uint8Array | Hex): Uint8Array {
+    return value instanceof Uint8Array ? value : hexToBytes(value)
+}
+
+/** Prepends the SEC1 `0x04` prefix to a 64-byte raw `X || Y` pair (secp256k1 or P-256). */
+export function prependUncompressedPrefix(coordinates: Uint8Array): Uint8Array {
+    const out = new Uint8Array(65)
+    out[0] = 0x04
+    out.set(coordinates, 1)
+    return out
+}
+
+/**
+ * Normalizes a device secret to a defensive copy of exactly 32 bytes.
+ * Accepts a 32-byte `Uint8Array` or a `0x`-prefixed 64-hex-char string;
+ * anything else throws {@link InvalidDeviceSecretError}.
+ */
+export function normalizeDeviceSecret(secret: Uint8Array | Hex | string): Uint8Array {
+    if (secret instanceof Uint8Array) {
+        if (secret.length !== 32) {
+            throw new InvalidDeviceSecretError()
+        }
+
+        return secret.slice()
+    }
+
+    if (typeof secret === "string") {
+        if (!secret.startsWith("0x") || secret.length !== 66 || !HEX_RE.test(secret.slice(2))) {
+            throw new InvalidDeviceSecretError()
+        }
+
+        return hexToBytes(secret)
+    }
+
+    throw new InvalidDeviceSecretError()
+}
+
+/**
+ * Normalizes a hardware ECDH shared secret to a defensive copy of exactly 32
+ * bytes. Same exactly-32-bytes contract as {@link normalizeDeviceSecret};
+ * rethrown as {@link InvalidEcdhSecretError} so callers don't conflate the
+ * two secrets by error code.
+ */
+export function normalizeEcdhSharedSecret(secret: Uint8Array | Hex | string): Uint8Array {
+    try {
+        return normalizeDeviceSecret(secret)
+    } catch (error) {
+        if (error instanceof InvalidDeviceSecretError) {
+            throw new InvalidEcdhSecretError()
+        }
+
+        throw error
+    }
+}

package/src/confirmation-key.ts

@@ -0,0 +1,50 @@
+import { p256 } from "@noble/curves/p256"
+import type { Hex } from "./types"
+import { bytesToBase64url, bytesToHex, prependUncompressedPrefix, toBytes } from "./bytes"
+import { sha256 } from "@noble/hashes/sha2"
+import { InvalidBindingInputError } from "./errors"
+
+/**
+ * Normalizes a P-256 `confirmationKey` to its raw 64-byte `X || Y`
+ * coordinates, validating that the point is on the curve. Accepts a 65-byte
+ * SEC1 uncompressed, 33-byte compressed, or 64-byte raw `X || Y` encoding.
+ */
+export function normalizeConfirmationKey(confirmationKey: Uint8Array | Hex): Uint8Array {
+    let bytes: Uint8Array
+
+    try {
+        bytes = toBytes(confirmationKey)
+    } catch {
+        throw new InvalidBindingInputError(
+            "normalizeConfirmationKey: expected raw bytes or a well-formed 0x-prefixed hex string"
+        )
+    }
+
+    if (bytes.length !== 33 && bytes.length !== 64 && bytes.length !== 65) {
+        throw new InvalidBindingInputError(
+            "normalizeConfirmationKey: expected a 65-byte uncompressed, 33-byte compressed, or 64-byte raw P-256 public key"
+        )
+    }
+
+    const sec1Bytes = bytes.length === 64 ? prependUncompressedPrefix(bytes) : bytes
+
+    try {
+        return p256.ProjectivePoint.fromHex(sec1Bytes).toRawBytes(false).slice(1)
+    } catch {
+        throw new InvalidBindingInputError("normalizeConfirmationKey: not a valid on-curve P-256 public key")
+    }
+}
+
+/**
+ * Computes the `confirmationKeyHash` embedded in the account binding message.
+ *
+ * NORMATIVE: the RFC 7638 JWK thumbprint of the P-256 confirmation key, i.e.
+ * `sha256(utf8('{"crv":"P-256","kty":"EC","x":<base64url X>,"y":<base64url Y>}'))`
+ */
+export function computeConfirmationKeyHash(confirmationKey: Uint8Array | Hex): Hex {
+    const coordinates = normalizeConfirmationKey(confirmationKey)
+    const x = bytesToBase64url(coordinates.slice(0, 32))
+    const y = bytesToBase64url(coordinates.slice(32))
+
+    return bytesToHex(sha256(`{"crv":"P-256","kty":"EC","x":"${x}","y":"${y}"}`))
+}

package/src/constants.ts

@@ -0,0 +1,40 @@
+/**
+ * Normative constants for the `v1` key derivation scheme. Changing any of
+ * these changes every derived key and `networkId`, so they MUST NOT change
+ * without a version bump (new `KEY_DERIVATION_VERSION` and domain strings).
+ */
+
+export const KEY_DERIVATION_VERSION = "v1" as const
+
+/** Fixed domain-separation message signed by {@link signDerivationMessage}. */
+export const FIXED_DOMAIN_MSG = "coordination-network/identity/v1" as const
+
+/** Domain-separation tag for deriving the account keypair from a device secret. */
+export const DOMAIN_ACCOUNT = "coordination-network/identity/v1/account" as const
+
+/** Domain-separation tag for deriving the auth keypair. */
+export const DOMAIN_AUTH = "coordination-network/identity/v1/auth" as const
+
+/** Domain-separation tag for deriving the Baby Jubjub EdDSA seed (the "fifth key") from the hardware ECDH shared secret. */
+export const DOMAIN_EDDSA = "coordination-network/identity/v1/eddsa" as const
+
+/** Domain-separation message hashed to the fixed NUMS P-256 peer point `Q` for the fifth-key ECDH (`eddsa-peer.ts`). */
+export const DOMAIN_EDDSA_PEER = "coordination-network/identity/v1/eddsa/peer" as const
+
+/**
+ * Byte length of `nonce` and `networkId` in the binding messages — fixed at
+ * 32 so the 64- vs 96-byte messages are injective.
+ */
+export const BINDING_NONCE_LENGTH = 32 as const
+
+/** SEC1-compressed secp256k1 public key length. */
+export const COMPRESSED_PUBLIC_KEY_LENGTH = 33 as const
+
+/** ERC-6538 scheme 1 meta-stealth address: compressed spending ‖ viewing public keys. */
+export const META_STEALTH_ADDRESS_LENGTH = 66 as const
+
+/** ERC-5564 offchain display prefix — never stored onchain. */
+export const META_STEALTH_URI_PREFIX = "st:eth:" as const
+
+/** ERC-5564 scheme id for secp256k1 with view tags. */
+export const ERC_5564_SCHEME_ID = 1 as const