@coordination-network/identity 0.0.1

package/dist/index.js

@@ -0,0 +1,893 @@
+import { bytesToHex as bytesToHex$1, hexToBytes as hexToBytes$1, utf8ToBytes, concatBytes } from '@noble/hashes/utils';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { bytesToNumberBE, numberToBytesBE } from '@noble/curves/utils';
+import { deriveSecretScalar, derivePublicKey } from '@zk-kit/eddsa-poseidon';
+import { poseidon2 } from 'poseidon-lite/poseidon2';
+import { hashToCurve, p256 } from '@noble/curves/p256';
+import { sha256 } from '@noble/hashes/sha2';
+
+/**
+ * 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).
+ */
+const KEY_DERIVATION_VERSION = "v1";
+/** Fixed domain-separation message signed by {@link signDerivationMessage}. */
+const FIXED_DOMAIN_MSG = "coordination-network/identity/v1";
+/** Domain-separation tag for deriving the account keypair from a device secret. */
+const DOMAIN_ACCOUNT = "coordination-network/identity/v1/account";
+/** Domain-separation tag for deriving the auth keypair. */
+const DOMAIN_AUTH = "coordination-network/identity/v1/auth";
+/** Domain-separation tag for deriving the Baby Jubjub EdDSA seed (the "fifth key") from the hardware ECDH shared secret. */
+const DOMAIN_EDDSA = "coordination-network/identity/v1/eddsa";
+/** Domain-separation message hashed to the fixed NUMS P-256 peer point `Q` for the fifth-key ECDH (`eddsa-peer.ts`). */
+const DOMAIN_EDDSA_PEER = "coordination-network/identity/v1/eddsa/peer";
+/**
+ * Byte length of `nonce` and `networkId` in the binding messages — fixed at
+ * 32 so the 64- vs 96-byte messages are injective.
+ */
+const BINDING_NONCE_LENGTH = 32;
+/** SEC1-compressed secp256k1 public key length. */
+const COMPRESSED_PUBLIC_KEY_LENGTH = 33;
+/** ERC-6538 scheme 1 meta-stealth address: compressed spending ‖ viewing public keys. */
+const META_STEALTH_ADDRESS_LENGTH = 66;
+/** ERC-5564 offchain display prefix — never stored onchain. */
+const META_STEALTH_URI_PREFIX = "st:eth:";
+/** ERC-5564 scheme id for secp256k1 with view tags. */
+const ERC_5564_SCHEME_ID = 1;
+
+/**
+ * Base error class for all errors thrown by this package, discriminated by
+ * `code` so callers can branch without `instanceof` across bundle boundaries.
+ */
+class KeygenError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "KeygenError";
+        this.code = code;
+    }
+}
+/** Thrown when a device secret does not satisfy the exactly-32-bytes contract. */
+class InvalidDeviceSecretError extends KeygenError {
+    constructor(message = "Invalid device secret: expected a 32-byte Uint8Array or a 0x-prefixed 64-character hex string") {
+        super("INVALID_DEVICE_SECRET", message);
+        this.name = "InvalidDeviceSecretError";
+    }
+}
+/** Thrown when key derivation fails for a reason unrelated to input shape. */
+class DerivationFailureError extends KeygenError {
+    constructor(message = "Key derivation failed") {
+        super("DERIVATION_FAILURE", message);
+        this.name = "DerivationFailureError";
+    }
+}
+/**
+ * Thrown for malformed credential-binding inputs; a well-formed signature
+ * that merely fails to verify returns `false` instead.
+ */
+class InvalidBindingInputError extends KeygenError {
+    constructor(message = "Invalid credential-binding input") {
+        super("INVALID_BINDING_INPUT", message);
+        this.name = "InvalidBindingInputError";
+    }
+}
+/** Thrown when a meta-stealth address fails to decode (bad prefix, length, hex, or curve point). */
+class InvalidMetaStealthAddressError extends KeygenError {
+    constructor(message = "Invalid meta-stealth address") {
+        super("INVALID_META_STEALTH_ADDRESS", message);
+        this.name = "InvalidMetaStealthAddressError";
+    }
+}
+/** Thrown when a hardware ECDH shared secret does not satisfy the exactly-32-bytes contract. */
+class InvalidEcdhSecretError extends KeygenError {
+    constructor(message = "Invalid ECDH shared secret: expected a 32-byte Uint8Array or a 0x-prefixed 64-character hex string") {
+        super("INVALID_ECDH_SECRET", message);
+        this.name = "InvalidEcdhSecretError";
+    }
+}
+/** Thrown when a public key is not the correct length */
+class InvalidPublicKeyLengthError extends KeygenError {
+    constructor(message = "Invalid public key length. Expected a 65-byte uncompressed SEC1 public key") {
+        super("INVALID_PUBLIC_KEY_LENGTH", message);
+        this.name = "InvalidPublicKeyLengthError";
+    }
+}
+
+const HEX_RE = /^[0-9a-fA-F]*$/;
+function hexToBytes(hex) {
+    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 hexToBytes$1(body);
+}
+function bytesToHex(bytes) {
+    return `0x${bytesToHex$1(bytes)}`;
+}
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/** Unpadded base64url (RFC 4648 §5) */
+function bytesToBase64url(bytes) {
+    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). */
+function base64urlToBytes(encoded) {
+    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;
+}
+function toBytes(value) {
+    return value instanceof Uint8Array ? value : hexToBytes(value);
+}
+/** Prepends the SEC1 `0x04` prefix to a 64-byte raw `X || Y` pair (secp256k1 or P-256). */
+function prependUncompressedPrefix(coordinates) {
+    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}.
+ */
+function normalizeDeviceSecret(secret) {
+    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.
+ */
+function normalizeEcdhSharedSecret(secret) {
+    try {
+        return normalizeDeviceSecret(secret);
+    }
+    catch (error) {
+        if (error instanceof InvalidDeviceSecretError) {
+            throw new InvalidEcdhSecretError();
+        }
+        throw error;
+    }
+}
+
+/**
+ * Generates a fresh 32-byte device secret from the platform CSPRNG
+ * (`globalThis.crypto.getRandomValues`). Throws if no secure RNG is available
+ * (e.g. React Native without the `react-native-get-random-values` polyfill).
+ */
+function generateDeviceSecret() {
+    const cryptoObj = globalThis.crypto;
+    if (typeof cryptoObj?.getRandomValues !== "function") {
+        throw new KeygenError("DERIVATION_FAILURE", "generateDeviceSecret: no secure random source (globalThis.crypto.getRandomValues) available");
+    }
+    const bytes = new Uint8Array(32);
+    cryptoObj.getRandomValues(bytes);
+    return bytesToHex(bytes);
+}
+
+const N = secp256k1.CURVE.n;
+/**
+ * Tests whether `scalar` is a valid secp256k1 private key: exactly 32 bytes
+ * encoding an integer in `[1, n)`.
+ */
+function isValidScalar(scalar) {
+    if (scalar.length !== 32) {
+        return false;
+    }
+    const value = BigInt(bytesToHex(scalar));
+    return value >= 1n && value < N;
+}
+/**
+ * Expands a 32-byte private scalar into a full {@link Secp256k1Keypair}, with
+ * all fields as lowercase `0x` hex.
+ *
+ * @throws {DerivationFailureError} if `scalar` is not in `[1, n)`
+ */
+function scalarToKeypair(scalar) {
+    if (!isValidScalar(scalar)) {
+        throw new DerivationFailureError("Derived scalar is not a valid secp256k1 private key in [1, n)");
+    }
+    return {
+        privateKey: bytesToHex(scalar),
+        publicKey: bytesToHex(secp256k1.getPublicKey(scalar, true)),
+        uncompressedPublicKey: bytesToHex(secp256k1.getPublicKey(scalar, false))
+    };
+}
+
+/** {@link hashToScalar} with an injectable hash, letting tests drive the reject/retry branch. */
+function hashToScalarWith(hashFn, tag, input) {
+    const tagBytes = utf8ToBytes(tag);
+    for (let counter = 0; counter <= 255; counter += 1) {
+        const candidate = hashFn(concatBytes(tagBytes, input, Uint8Array.of(counter)));
+        if (isValidScalar(candidate)) {
+            return candidate;
+        }
+    }
+    throw new DerivationFailureError("hashToScalar: exhausted all 256 counter values without a valid scalar");
+}
+/**
+ * Deterministically derives a secp256k1 private scalar from a domain tag and
+ * input bytes.
+ *
+ * NORMATIVE: for `counter = 0..255`, return the first
+ * `keccak256(utf8(tag) || input || [counter])` whose big-endian value lies in
+ * `[1, n)`. Out-of-range candidates have probability ~`2^-128`, so exhaustion
+ * is unreachable.
+ */
+function hashToScalar(tag, input) {
+    return hashToScalarWith(keccak_256, tag, input);
+}
+
+/**
+ * Derives the root secp256k1 account keypair from a 32-byte device secret.
+ *
+ * NORMATIVE: `accountPrivKey = hashToScalar(DOMAIN_ACCOUNT, deviceSecret)`.
+ */
+function deriveAccountKeypair(deviceSecret) {
+    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
+ */
+function normalizeSignature64(sig64) {
+    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
+ */
+function eip191Digest(message) {
+    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.
+ */
+function signDerivationMessage(accountPrivateKey) {
+    const privateKey = toBytes(accountPrivateKey);
+    const digest = eip191Digest(utf8ToBytes(FIXED_DOMAIN_MSG));
+    const signature = secp256k1.sign(digest, privateKey, { lowS: true });
+    return bytesToHex(signature.toCompactRawBytes());
+}
+
+/**
+ * Derives the spending and viewing secp256k1 keypairs from the 64-byte
+ * compact derivation-message signature.
+ *
+ * NORMATIVE (FluidKey `generateKeysFromSignature` semantics): with
+ * `r = sig[0..32]` and `s = sig[32..64]`, `spendingPrivKey = keccak256(r)`
+ * and `viewingPrivKey = keccak256(s)`. No reject/retry — the hash output is
+ * used directly and validated to be in `[1, n)` by {@link scalarToKeypair}.
+ *
+ * `sig64` is unauthenticated — prefer {@link deriveKeys} (see `DERIVATION.md`).
+ */
+function deriveStealthKeys(sig64) {
+    const signature = normalizeSignature64(sig64);
+    const r = signature.slice(0, 32);
+    const s = signature.slice(32, 64);
+    return {
+        spending: scalarToKeypair(keccak_256(r)),
+        viewing: scalarToKeypair(keccak_256(s))
+    };
+}
+
+/**
+ * The ERC-5564 hashed shared secret: keccak256 of the 33-byte compressed
+ * ECDH point.
+ *
+ * The sender can pass (ephemeralPrivateKey, viewingPublicKey).
+ * The recipient can pass (viewingPrivateKey, ephemeralPublicKey).
+ */
+function computeSharedSecret({ privateKey, publicKey }) {
+    const sharedSecret = secp256k1.getSharedSecret(privateKey.slice(2), publicKey.slice(2), true);
+    return keccak_256(sharedSecret);
+}
+
+/**
+ * First byte of the hashed shared secret, published in announcements so
+ * scanners can skip 255/256 non-matching shared secrets.
+ */
+function getViewTag(hashedSharedSecret) {
+    return hashedSharedSecret[0];
+}
+
+/**
+ * Generates stealth public key. ERC-5564 scheme 1: P_stealth = P_spend + (s_h mod n)·G,
+ * returned as a 65-byte uncompressed public key.
+ */
+function getStealthPublicKey({ spendingPublicKey, hashedSharedSecret }) {
+    const sharedSecretScalar = bytesToNumberBE(hashedSharedSecret) % secp256k1.Point.CURVE().n;
+    return secp256k1.Point.fromHex(spendingPublicKey.slice(2))
+        .add(secp256k1.Point.BASE.multiply(sharedSecretScalar))
+        .toBytes(false);
+}
+
+/**
+ * Derive Ethereum address from public key: keccak256 of the 64-byte X || Y
+ * coordinates (65 bytes without 0x04 prefix stripped), then last 20 bytes.
+ */
+function publicKeyToAddress(publicKey) {
+    if (publicKey.length !== 65) {
+        throw new InvalidPublicKeyLengthError();
+    }
+    const publicKeyHash = keccak_256(publicKey.slice(1));
+    return `0x${bytesToHex(publicKeyHash).slice(-40)}`;
+}
+
+/**
+ * A fresh CSPRNG keypair for one load. MUST be single-use — reusing an
+ * ephemeral key derives the same stealth address twice.
+ */
+function generateEphemeralKey() {
+    return scalarToKeypair(hexToBytes(generateDeviceSecret()));
+}
+
+/**
+ * Derives a fresh stealth address from the
+ * recipient's spending and viewing public keys.
+ */
+function generateStealthAddress({ viewingPublicKey, spendingPublicKey, ephemeralPrivateKey }) {
+    const hashedSharedSecret = computeSharedSecret({
+        privateKey: ephemeralPrivateKey,
+        publicKey: viewingPublicKey
+    });
+    const stealthPublicKey = getStealthPublicKey({ spendingPublicKey, hashedSharedSecret });
+    return publicKeyToAddress(stealthPublicKey);
+}
+
+/**
+ * Recovers the private key controlling a stealth address,
+ * (p_spend + s_h) mod n.
+ */
+function generateStealthPrivateKey({ ephemeralPublicKey, viewingPrivateKey, spendingPrivateKey }) {
+    const secretHash = computeSharedSecret({
+        privateKey: viewingPrivateKey,
+        publicKey: ephemeralPublicKey
+    });
+    const privateKey = (bytesToNumberBE(hexToBytes(spendingPrivateKey)) + bytesToNumberBE(secretHash)) % secp256k1.Point.CURVE().n;
+    return bytesToHex(numberToBytesBE(privateKey, 32));
+}
+
+/**
+ * Checks whether an announcement is addressed to a recipient: filters by
+ * view-tag first, then full address recompute.
+ */
+function checkStealthAddress({ stealthAddress, ephemeralPublicKey, spendingPublicKey, viewingPrivateKey, viewTag }) {
+    const hashedSharedSecret = computeSharedSecret({
+        privateKey: viewingPrivateKey,
+        publicKey: ephemeralPublicKey
+    });
+    if (viewTag !== getViewTag(hashedSharedSecret)) {
+        return false;
+    }
+    const stealthPublicKey = getStealthPublicKey({ spendingPublicKey, hashedSharedSecret });
+    const expectedStealthAddress = publicKeyToAddress(stealthPublicKey);
+    return expectedStealthAddress.toLowerCase() === stealthAddress.toLowerCase();
+}
+
+/** Checked per key, not on the concatenation: 32 + 34 bytes hits the right total but splits wrong. */
+function assertCompressedPublicKey(publicKey, label) {
+    if (!/^0x[0-9a-fA-F]+$/.test(publicKey) || (publicKey.length - 2) / 2 !== COMPRESSED_PUBLIC_KEY_LENGTH) {
+        throw new InvalidMetaStealthAddressError(
+        // Never echo the value: a 32-byte private key passed here by mistake lands on this branch.
+        `${label} public key must be ${COMPRESSED_PUBLIC_KEY_LENGTH} bytes of SEC1-compressed hex`);
+    }
+    const prefix = publicKey.slice(2, 4);
+    if (prefix !== "02" && prefix !== "03") {
+        throw new InvalidMetaStealthAddressError(`${label} public key must start with 0x02 or 0x03, got 0x${prefix}`);
+    }
+    try {
+        secp256k1.Point.fromHex(publicKey.slice(2));
+    }
+    catch {
+        throw new InvalidMetaStealthAddressError(`${label} public key is not a point on secp256k1`);
+    }
+}
+
+/** Validates 66-byte meta stealth address: shape and curve checks */
+function validateMetaStealthAddress(metaStealthAddress) {
+    if (!metaStealthAddress.startsWith("0x")) {
+        return false;
+    }
+    const cleanedMetaStealthAddress = metaStealthAddress.slice(2);
+    try {
+        assertCompressedPublicKey(`0x${cleanedMetaStealthAddress.slice(0, 66)}`, "spending");
+        assertCompressedPublicKey(`0x${cleanedMetaStealthAddress.slice(66)}`, "viewing");
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * The 66-byte compressed spending || viewing concatenation the onchain registry stores. Throws
+ * InvalidMetaStealthAddressError, naming the offending key, so it can be used before registering.
+ */
+function encodeMetaStealthAddress({ spendingPublicKey, viewingPublicKey }) {
+    assertCompressedPublicKey(spendingPublicKey, "spending");
+    assertCompressedPublicKey(viewingPublicKey, "viewing");
+    return `${spendingPublicKey}${viewingPublicKey.slice(2)}`;
+}
+
+/** Takes the encoded address, so it also formats one read back from a registry. */
+function metaStealthAddressUri(metaStealthAddress) {
+    return `${META_STEALTH_URI_PREFIX}${metaStealthAddress}`;
+}
+
+/** The st:eth:0x… display form (ERC-5564 URI). Not stored onchain. */
+function encodeMetaStealthAddressUri(publicKeys) {
+    return metaStealthAddressUri(encodeMetaStealthAddress(publicKeys));
+}
+
+/**
+ * Splits a 66-byte meta-stealth address (raw hex or `st:eth:` prefixed) into its
+ * spending and viewing public keys.
+ */
+function decodeMetaStealthAddress(metaStealthAddress) {
+    const hexMetaStealthAddress = metaStealthAddress.startsWith(META_STEALTH_URI_PREFIX)
+        ? metaStealthAddress.slice(META_STEALTH_URI_PREFIX.length)
+        : metaStealthAddress;
+    if (!validateMetaStealthAddress(hexMetaStealthAddress)) {
+        throw new InvalidMetaStealthAddressError();
+    }
+    const cleanedMetaStealthAddress = hexMetaStealthAddress.slice(2);
+    return {
+        spendingPublicKey: `0x${cleanedMetaStealthAddress.slice(0, 66)}`,
+        viewingPublicKey: `0x${cleanedMetaStealthAddress.slice(66)}`
+    };
+}
+
+/**
+ * Builds an ERC-5564 announcement payload for a fresh stealth address,
+ * generates ephemeral key internally. The view tag is the
+ * first and only metadata byte.
+ */
+function buildAnnouncement({ metaStealthAddress }) {
+    const { spendingPublicKey, viewingPublicKey } = decodeMetaStealthAddress(metaStealthAddress);
+    const ephemeralKey = generateEphemeralKey();
+    const hashedSharedSecret = computeSharedSecret({
+        privateKey: ephemeralKey.privateKey,
+        publicKey: viewingPublicKey
+    });
+    const stealthPublicKey = getStealthPublicKey({ spendingPublicKey, hashedSharedSecret });
+    return {
+        schemeId: ERC_5564_SCHEME_ID,
+        stealthAddress: publicKeyToAddress(stealthPublicKey),
+        ephemeralPublicKey: ephemeralKey.publicKey,
+        metadata: bytesToHex(Uint8Array.of(getViewTag(hashedSharedSecret)))
+    };
+}
+
+/**
+ * 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`).
+ */
+function deriveAuthKeypair(sig64) {
+    const signature = normalizeSignature64(sig64);
+    const scalar = hashToScalar(DOMAIN_AUTH, signature);
+    return scalarToKeypair(scalar);
+}
+
+/** Baby Jubjub EdDSA "fifth key" derivation — see `DERIVATION.md` §12. */
+/**
+ * Derives the Baby Jubjub EdDSA keypair and Semaphore-v4 identity commitment
+ * (the "fifth key"), rooted in a hardware ECDH shared secret.
+ *
+ * NORMATIVE (`DERIVATION.md` §12): `ecdhSharedSecret = X(hwPriv · Q)` for the
+ * fixed NUMS peer point `Q` (`eddsa-peer.ts`), computed natively by the
+ * caller — the library never talks to the Keystore, it only takes the raw
+ * 32-byte result. `seed = keccak256(utf8(DOMAIN_EDDSA) || ecdhSharedSecret)`,
+ * fed to `@zk-kit/eddsa-poseidon` as raw bytes (MUST NOT be the hex string,
+ * see §12.4); `commitment = poseidon2([x, y])`.
+ *
+ * @throws {InvalidEcdhSecretError} if `ecdhSharedSecret` is not exactly 32 bytes
+ */
+function deriveEddsaKeypair(ecdhSharedSecret) {
+    const secret = normalizeEcdhSharedSecret(ecdhSharedSecret);
+    const seed = keccak_256(concatBytes(utf8ToBytes(DOMAIN_EDDSA), secret));
+    const secretScalar = deriveSecretScalar(seed);
+    const publicKey = derivePublicKey(seed);
+    const commitment = poseidon2(publicKey);
+    return {
+        seed: bytesToHex(seed),
+        secretScalar,
+        publicKey,
+        commitment
+    };
+}
+
+/** Fixed NUMS P-256 peer point `Q` for the fifth-key ECDH — see `DERIVATION.md` §12. */
+/**
+ * NORMATIVE: `Q = hashToCurve(utf8(DOMAIN_EDDSA_PEER))` (RFC 9380
+ * `P256_XMD:SHA-256_SSWU_RO_`, suite-default DST). Nobody knows `dlog(Q)`,
+ * so `hwPriv · Q` is computable only by the device that holds `hwPriv`.
+ * 65-byte SEC1 uncompressed encoding, `0x04`-prefixed.
+ */
+const EDDSA_PEER_POINT_HEX = "0x045db1cabf31539848bf802ad49a94ad8f8e3d52e75bb53aa4552d7cf836eba054213badca0cf4ba6daf8c146d3415d9ae1905440781dc5f08e6e946a471af99e9";
+/** Fresh copy of {@link EDDSA_PEER_POINT_HEX} as raw bytes. */
+function eddsaPeerPointBytes() {
+    return hexToBytes(EDDSA_PEER_POINT_HEX);
+}
+/**
+ * Reproduces `Q` from its RFC 9380 provenance, independent of the pinned
+ * constant — the evidence that {@link EDDSA_PEER_POINT_HEX} is a NUMS point.
+ *
+ * `hashToCurve` returns an `H2CPoint`, which lacks `toRawBytes`; round-trip
+ * through `ProjectivePoint.fromAffine` to get the SEC1 encoding.
+ */
+function computeEddsaPeerPoint() {
+    const point = hashToCurve(utf8ToBytes(DOMAIN_EDDSA_PEER));
+    return p256.ProjectivePoint.fromAffine(point.toAffine()).toRawBytes(false);
+}
+
+/**
+ * Computes the bytes32 `networkId` from an uncompressed secp256k1 public key
+ * (65-byte SEC1 `0x04`-prefixed or 64-byte raw `X || Y`).
+ *
+ * NORMATIVE: `networkId = keccak256(X || Y)` — the SEC1 prefix is stripped.
+ * The last 20 bytes are the account's Ethereum address.
+ */
+function computeNetworkId(uncompressedPublicKey) {
+    const bytes = toBytes(uncompressedPublicKey);
+    let coordinates;
+    if (bytes.length === 65 && bytes[0] === 0x04) {
+        coordinates = bytes.slice(1);
+    }
+    else if (bytes.length === 64) {
+        coordinates = bytes;
+    }
+    else {
+        throw new TypeError("computeNetworkId: expected a 65-byte 0x04-prefixed or 64-byte raw uncompressed public key");
+    }
+    return bytesToHex(keccak_256(coordinates));
+}
+
+/**
+ * Derives the full `v1` device identity — `networkId` plus the four-key
+ * all-secp256k1 model — from a single device secret.
+ *
+ * Pipeline (NORMATIVE):
+ * 1. `account = deriveAccountKeypair(deviceSecret)`
+ * 2. `networkId = computeNetworkId(account.uncompressedPublicKey)`
+ * 3. `sig = signDerivationMessage(account.privateKey)` (EIP-191, deterministic)
+ * 4. `{ spending, viewing } = deriveStealthKeys(sig)` (FluidKey semantics)
+ * 5. `auth = deriveAuthKeypair(sig)`
+ */
+function deriveKeys(deviceSecret) {
+    const account = deriveAccountKeypair(deviceSecret);
+    const networkId = computeNetworkId(account.uncompressedPublicKey);
+    const signature = signDerivationMessage(account.privateKey);
+    const { spending, viewing } = deriveStealthKeys(signature);
+    const auth = deriveAuthKeypair(signature);
+    return {
+        version: KEY_DERIVATION_VERSION,
+        networkId,
+        account,
+        spending,
+        viewing,
+        auth
+    };
+}
+/** Derives only the `networkId` — equal to `deriveKeys(deviceSecret).networkId`, minus the signature work. */
+function deriveNetworkId(deviceSecret) {
+    const account = deriveAccountKeypair(deviceSecret);
+    return computeNetworkId(account.uncompressedPublicKey);
+}
+
+/**
+ * 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.
+ */
+function normalizeConfirmationKey(confirmationKey) {
+    let bytes;
+    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>}'))`
+ */
+function computeConfirmationKeyHash(confirmationKey) {
+    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}"}`));
+}
+
+/**
+ * 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.
+ */
+function toBindingBytes(value, label) {
+    try {
+        return toBytes(value);
+    }
+    catch {
+        throw new InvalidBindingInputError(`${label}: expected raw bytes or a well-formed 0x-prefixed hex string`);
+    }
+}
+function decodeAndValidateNonceAndNetworkId(nonce, networkId) {
+    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) {
+    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) {
+    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) {
+    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.
+ */
+function buildDeviceBindingMessage(nonce, networkId, holderKeyCommitment) {
+    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.
+ */
+function buildAccountBindingMessage(nonce, confirmationKey, networkId) {
+    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.
+ */
+function buildBindingMessages(nonce, accountUncompressedPublicKey, confirmationKey, holderKeyCommitment) {
+    let networkId;
+    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`).
+ */
+function signAccountBinding(accountPrivateKey, nonce, confirmationKey) {
+    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`.
+ */
+function verifyAccountBindingSignature({ nonce, confirmationKey, accountPublicKey, signature }) {
+    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).
+ */
+function verifyDeviceBindingSignature({ nonce, networkId, confirmationKey, holderKeyCommitment, signature }) {
+    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.
+ */
+function verifyCredentialBinding({ nonce, accountPublicKey, confirmationKey, holderKeyCommitment, accountSignature, deviceSignature }) {
+    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 };
+}
+
+export { BINDING_NONCE_LENGTH, COMPRESSED_PUBLIC_KEY_LENGTH, DOMAIN_ACCOUNT, DOMAIN_AUTH, DOMAIN_EDDSA, DOMAIN_EDDSA_PEER, DerivationFailureError, EDDSA_PEER_POINT_HEX, ERC_5564_SCHEME_ID, FIXED_DOMAIN_MSG, InvalidBindingInputError, InvalidDeviceSecretError, InvalidEcdhSecretError, InvalidMetaStealthAddressError, InvalidPublicKeyLengthError, KEY_DERIVATION_VERSION, KeygenError, META_STEALTH_ADDRESS_LENGTH, META_STEALTH_URI_PREFIX, base64urlToBytes, buildAccountBindingMessage, buildAnnouncement, buildBindingMessages, buildDeviceBindingMessage, bytesToBase64url, bytesToHex, checkStealthAddress, computeConfirmationKeyHash, computeEddsaPeerPoint, computeNetworkId, computeSharedSecret, decodeMetaStealthAddress, deriveAccountKeypair, deriveAuthKeypair, deriveEddsaKeypair, deriveKeys, deriveNetworkId, deriveStealthKeys, eddsaPeerPointBytes, encodeMetaStealthAddress, encodeMetaStealthAddressUri, generateDeviceSecret, generateEphemeralKey, generateStealthAddress, generateStealthPrivateKey, getStealthPublicKey, getViewTag, hashToScalar, hashToScalarWith, hexToBytes, isValidScalar, metaStealthAddressUri, normalizeConfirmationKey, normalizeDeviceSecret, normalizeEcdhSharedSecret, publicKeyToAddress, scalarToKeypair, signAccountBinding, signDerivationMessage, validateMetaStealthAddress, verifyAccountBindingSignature, verifyCredentialBinding, verifyDeviceBindingSignature };