@coordination-network/identity 0.0.1

package/src/derive.ts

@@ -0,0 +1,41 @@
+import type { DerivedKeys, Hex } from "./types"
+import { KEY_DERIVATION_VERSION } from "./constants"
+import { deriveAccountKeypair, signDerivationMessage } from "./account"
+import { deriveStealthKeys } from "./stealthAddresses/deriveStealthKeys"
+import { deriveAuthKeypair } from "./auth"
+import { computeNetworkId } from "./network-id"
+
+/**
+ * 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)`
+ */
+export function deriveKeys(deviceSecret: Uint8Array | Hex): DerivedKeys {
+    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. */
+export function deriveNetworkId(deviceSecret: Uint8Array | Hex): Hex {
+    const account = deriveAccountKeypair(deviceSecret)
+
+    return computeNetworkId(account.uncompressedPublicKey)
+}

package/src/device-secret.ts

@@ -0,0 +1,24 @@
+import type { Hex } from "./types"
+import { bytesToHex } from "./bytes"
+import { KeygenError } from "./errors"
+
+/**
+ * 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).
+ */
+export function generateDeviceSecret(): Hex {
+    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)
+}

package/src/eddsa-peer.ts

@@ -0,0 +1,32 @@
+/** Fixed NUMS P-256 peer point `Q` for the fifth-key ECDH — see `DERIVATION.md` §12. */
+
+import { hashToCurve, p256 } from "@noble/curves/p256"
+import { hexToBytes, utf8ToBytes } from "./bytes"
+import { DOMAIN_EDDSA_PEER } from "./constants"
+
+/**
+ * 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.
+ */
+export const EDDSA_PEER_POINT_HEX =
+    "0x045db1cabf31539848bf802ad49a94ad8f8e3d52e75bb53aa4552d7cf836eba054213badca0cf4ba6daf8c146d3415d9ae1905440781dc5f08e6e946a471af99e9" as const
+
+/** Fresh copy of {@link EDDSA_PEER_POINT_HEX} as raw bytes. */
+export function eddsaPeerPointBytes(): Uint8Array {
+    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.
+ */
+export function computeEddsaPeerPoint(): Uint8Array {
+    const point = hashToCurve(utf8ToBytes(DOMAIN_EDDSA_PEER))
+
+    return p256.ProjectivePoint.fromAffine(point.toAffine()).toRawBytes(false)
+}

package/src/eddsa.ts

@@ -0,0 +1,37 @@
+/** Baby Jubjub EdDSA "fifth key" derivation — see `DERIVATION.md` §12. */
+
+import { keccak_256 } from "@noble/hashes/sha3"
+import { deriveSecretScalar, derivePublicKey } from "@zk-kit/eddsa-poseidon"
+import { poseidon2 } from "poseidon-lite/poseidon2"
+import type { EddsaKeypair, Hex } from "./types"
+import { DOMAIN_EDDSA } from "./constants"
+import { bytesToHex, concatBytes, normalizeEcdhSharedSecret, utf8ToBytes } from "./bytes"
+
+/**
+ * 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
+ */
+export function deriveEddsaKeypair(ecdhSharedSecret: Uint8Array | Hex): EddsaKeypair {
+    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
+    }
+}

package/src/errors.ts

@@ -0,0 +1,76 @@
+export type KeygenErrorCode =
+    | "INVALID_DEVICE_SECRET"
+    | "DERIVATION_FAILURE"
+    | "INVALID_BINDING_INPUT"
+    | "INVALID_ECDH_SECRET"
+    | "INVALID_META_STEALTH_ADDRESS"
+    | "INVALID_PUBLIC_KEY_LENGTH"
+
+/**
+ * Base error class for all errors thrown by this package, discriminated by
+ * `code` so callers can branch without `instanceof` across bundle boundaries.
+ */
+export class KeygenError extends Error {
+    readonly code: KeygenErrorCode
+
+    constructor(code: KeygenErrorCode, message: string) {
+        super(message)
+        this.name = "KeygenError"
+        this.code = code
+    }
+}
+
+/** Thrown when a device secret does not satisfy the exactly-32-bytes contract. */
+export class InvalidDeviceSecretError extends KeygenError {
+    constructor(
+        message: string = "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. */
+export class DerivationFailureError extends KeygenError {
+    constructor(message: string = "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.
+ */
+export class InvalidBindingInputError extends KeygenError {
+    constructor(message: string = "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). */
+export class InvalidMetaStealthAddressError extends KeygenError {
+    constructor(message: string = "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. */
+export class InvalidEcdhSecretError extends KeygenError {
+    constructor(
+        message: string = "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 */
+export class InvalidPublicKeyLengthError extends KeygenError {
+    constructor(message: string = "Invalid public key length. Expected a 65-byte uncompressed SEC1 public key") {
+        super("INVALID_PUBLIC_KEY_LENGTH", message)
+        this.name = "InvalidPublicKeyLengthError"
+    }
+}

package/src/hash-to-scalar.ts

@@ -0,0 +1,35 @@
+import { keccak_256 } from "@noble/hashes/sha3"
+import { concatBytes, utf8ToBytes } from "./bytes"
+import { DerivationFailureError } from "./errors"
+import { isValidScalar } from "./keypair"
+
+/** A 32-byte-output hash function, e.g. `keccak_256`. */
+export type HashFn = (input: Uint8Array) => Uint8Array
+
+/** {@link hashToScalar} with an injectable hash, letting tests drive the reject/retry branch. */
+export function hashToScalarWith(hashFn: HashFn, tag: string, input: Uint8Array): Uint8Array {
+    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.
+ */
+export function hashToScalar(tag: string, input: Uint8Array): Uint8Array {
+    return hashToScalarWith(keccak_256, tag, input)
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@coordination-network/identity` — deterministic device key derivation
+ * (`networkId` and four secp256k1 keys from one device secret, plus a
+ * hardware-rooted Baby Jubjub EdDSA fifth key) and the credential dual
+ * proof-of-possession binding.
+ */
+
+export * from "./types"
+export * from "./constants"
+export * from "./errors"
+export {
+    base64urlToBytes,
+    bytesToBase64url,
+    bytesToHex,
+    hexToBytes,
+    normalizeDeviceSecret,
+    normalizeEcdhSharedSecret
+} from "./bytes"
+export { generateDeviceSecret } from "./device-secret"
+export { hashToScalar, hashToScalarWith } from "./hash-to-scalar"
+export type { HashFn } from "./hash-to-scalar"
+export { isValidScalar, scalarToKeypair } from "./keypair"
+export { deriveAccountKeypair, signDerivationMessage } from "./account"
+export { deriveStealthKeys } from "./stealthAddresses/deriveStealthKeys"
+export { computeSharedSecret } from "./stealthAddresses/computeSharedSecret"
+export { getViewTag } from "./stealthAddresses/getViewTag"
+export { getStealthPublicKey } from "./stealthAddresses/getStealthPublicKey"
+export { publicKeyToAddress } from "./stealthAddresses/publicKeyToAddress"
+export { generateEphemeralKey } from "./stealthAddresses/generateEphemeralKey"
+export { generateStealthAddress } from "./stealthAddresses/generateStealthAddress"
+export { generateStealthPrivateKey } from "./stealthAddresses/generateStealthPrivateKey"
+export { checkStealthAddress } from "./stealthAddresses/checkStealthAddress"
+export { validateMetaStealthAddress } from "./stealthAddresses/validateMetaStealthAddress"
+export { encodeMetaStealthAddress } from "./stealthAddresses/encodeMetaStealthAddress"
+export { encodeMetaStealthAddressUri } from "./stealthAddresses/encodeMetaStealthAddressUri"
+export { metaStealthAddressUri } from "./stealthAddresses/metaStealthAddressUri"
+export { decodeMetaStealthAddress } from "./stealthAddresses/decodeMetaStealthAddress"
+export { buildAnnouncement } from "./stealthAddresses/buildAnnouncement"
+export { deriveAuthKeypair } from "./auth"
+export { deriveEddsaKeypair } from "./eddsa"
+export { EDDSA_PEER_POINT_HEX, eddsaPeerPointBytes, computeEddsaPeerPoint } from "./eddsa-peer"
+export { computeNetworkId } from "./network-id"
+export { deriveKeys, deriveNetworkId } from "./derive"
+export { normalizeConfirmationKey, computeConfirmationKeyHash } from "./confirmation-key"
+export {
+    buildDeviceBindingMessage,
+    buildAccountBindingMessage,
+    buildBindingMessages,
+    signAccountBinding,
+    verifyAccountBindingSignature,
+    verifyDeviceBindingSignature,
+    verifyCredentialBinding
+} from "./binding"

package/src/keypair.ts

@@ -0,0 +1,38 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import type { Secp256k1Keypair } from "./types"
+import { bytesToHex } from "./bytes"
+import { DerivationFailureError } from "./errors"
+
+const N = secp256k1.CURVE.n
+
+/**
+ * Tests whether `scalar` is a valid secp256k1 private key: exactly 32 bytes
+ * encoding an integer in `[1, n)`.
+ */
+export function isValidScalar(scalar: Uint8Array): boolean {
+    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)`
+ */
+export function scalarToKeypair(scalar: Uint8Array): Secp256k1Keypair {
+    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))
+    }
+}

package/src/network-id.ts

@@ -0,0 +1,26 @@
+import { keccak_256 } from "@noble/hashes/sha3"
+import type { Hex } from "./types"
+import { bytesToHex, toBytes } from "./bytes"
+
+/**
+ * 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.
+ */
+export function computeNetworkId(uncompressedPublicKey: Uint8Array | Hex): Hex {
+    const bytes = toBytes(uncompressedPublicKey)
+
+    let coordinates: Uint8Array
+
+    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))
+}

package/src/stealthAddresses/assertCompressedPublicKey.ts

@@ -0,0 +1,25 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import { Hex } from "../types"
+import { COMPRESSED_PUBLIC_KEY_LENGTH } from "../constants"
+import { InvalidMetaStealthAddressError } from "../errors"
+
+/** Checked per key, not on the concatenation: 32 + 34 bytes hits the right total but splits wrong. */
+export function assertCompressedPublicKey(publicKey: Hex, label: string): void {
+    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`)
+    }
+}

package/src/stealthAddresses/buildAnnouncement.ts

@@ -0,0 +1,37 @@
+import { Address, Hex } from "../types"
+import { ERC_5564_SCHEME_ID } from "../constants"
+import { bytesToHex } from "../bytes"
+import { decodeMetaStealthAddress } from "./decodeMetaStealthAddress"
+import { generateEphemeralKey } from "./generateEphemeralKey"
+import { computeSharedSecret } from "./computeSharedSecret"
+import { getStealthPublicKey } from "./getStealthPublicKey"
+import { publicKeyToAddress } from "./publicKeyToAddress"
+import { getViewTag } from "./getViewTag"
+
+/**
+ * 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.
+ */
+export function buildAnnouncement({ metaStealthAddress }: { metaStealthAddress: Hex }): {
+    schemeId: typeof ERC_5564_SCHEME_ID
+    stealthAddress: Address
+    ephemeralPublicKey: Hex
+    metadata: Hex
+} {
+    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)))
+    }
+}

package/src/stealthAddresses/checkStealthAddress.ts

@@ -0,0 +1,37 @@
+import { Address, Hex } from "../types"
+import { computeSharedSecret } from "./computeSharedSecret"
+import { getViewTag } from "./getViewTag"
+import { getStealthPublicKey } from "./getStealthPublicKey"
+import { publicKeyToAddress } from "./publicKeyToAddress"
+
+/**
+ * Checks whether an announcement is addressed to a recipient: filters by
+ * view-tag first, then full address recompute.
+ */
+export function checkStealthAddress({
+    stealthAddress,
+    ephemeralPublicKey,
+    spendingPublicKey,
+    viewingPrivateKey,
+    viewTag
+}: {
+    stealthAddress: Address
+    ephemeralPublicKey: Hex
+    spendingPublicKey: Hex
+    viewingPrivateKey: Hex
+    viewTag: number
+}): boolean {
+    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()
+}

package/src/stealthAddresses/computeSharedSecret.ts

@@ -0,0 +1,16 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import { keccak_256 } from "@noble/hashes/sha3"
+import { Hex } from "../types"
+
+/**
+ * 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).
+ */
+export function computeSharedSecret({ privateKey, publicKey }: { privateKey: Hex; publicKey: Hex }): Uint8Array {
+    const sharedSecret = secp256k1.getSharedSecret(privateKey.slice(2), publicKey.slice(2), true)
+
+    return keccak_256(sharedSecret)
+}

package/src/stealthAddresses/decodeMetaStealthAddress.ts

@@ -0,0 +1,27 @@
+import { Hex } from "../types"
+import { META_STEALTH_URI_PREFIX } from "../constants"
+import { validateMetaStealthAddress } from "./validateMetaStealthAddress"
+import { InvalidMetaStealthAddressError } from "../errors"
+
+/**
+ * Splits a 66-byte meta-stealth address (raw hex or `st:eth:` prefixed) into its
+ * spending and viewing public keys.
+ */
+export function decodeMetaStealthAddress(metaStealthAddress: string): {
+    spendingPublicKey: Hex
+    viewingPublicKey: Hex
+} {
+    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)}`
+    }
+}

package/src/stealthAddresses/deriveStealthKeys.ts

@@ -0,0 +1,30 @@
+import { keccak_256 } from "@noble/hashes/sha3"
+import type { Hex, Secp256k1Keypair } from "../types"
+import { normalizeSignature64 } from "../account"
+import { scalarToKeypair } from "../keypair"
+
+/**
+ * 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`).
+ */
+export function deriveStealthKeys(sig64: Uint8Array | Hex): {
+    spending: Secp256k1Keypair
+    viewing: Secp256k1Keypair
+} {
+    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))
+    }
+}

package/src/stealthAddresses/encodeMetaStealthAddress.ts

@@ -0,0 +1,19 @@
+import { Hex } from "../types"
+import { assertCompressedPublicKey } from "./assertCompressedPublicKey"
+
+/**
+ * The 66-byte compressed spending || viewing concatenation the onchain registry stores. Throws
+ * InvalidMetaStealthAddressError, naming the offending key, so it can be used before registering.
+ */
+export function encodeMetaStealthAddress({
+    spendingPublicKey,
+    viewingPublicKey
+}: {
+    spendingPublicKey: Hex
+    viewingPublicKey: Hex
+}): Hex {
+    assertCompressedPublicKey(spendingPublicKey, "spending")
+    assertCompressedPublicKey(viewingPublicKey, "viewing")
+
+    return `${spendingPublicKey}${viewingPublicKey.slice(2)}`
+}

package/src/stealthAddresses/encodeMetaStealthAddressUri.ts

@@ -0,0 +1,8 @@
+import { Hex } from "../types"
+import { encodeMetaStealthAddress } from "./encodeMetaStealthAddress"
+import { metaStealthAddressUri } from "./metaStealthAddressUri"
+
+/** The st:eth:0x… display form (ERC-5564 URI). Not stored onchain. */
+export function encodeMetaStealthAddressUri(publicKeys: { spendingPublicKey: Hex; viewingPublicKey: Hex }): string {
+    return metaStealthAddressUri(encodeMetaStealthAddress(publicKeys))
+}

package/src/stealthAddresses/generateEphemeralKey.ts

@@ -0,0 +1,12 @@
+import { scalarToKeypair } from "../keypair"
+import { hexToBytes } from "../bytes"
+import { Secp256k1Keypair } from "../types"
+import { generateDeviceSecret } from "../device-secret"
+
+/**
+ * A fresh CSPRNG keypair for one load. MUST be single-use — reusing an
+ * ephemeral key derives the same stealth address twice.
+ */
+export function generateEphemeralKey(): Secp256k1Keypair {
+    return scalarToKeypair(hexToBytes(generateDeviceSecret()))
+}

package/src/stealthAddresses/generateStealthAddress.ts

@@ -0,0 +1,27 @@
+import { Address, Hex } from "../types"
+import { computeSharedSecret } from "./computeSharedSecret"
+import { getStealthPublicKey } from "./getStealthPublicKey"
+import { publicKeyToAddress } from "./publicKeyToAddress"
+
+/**
+ * Derives a fresh stealth address from the
+ * recipient's spending and viewing public keys.
+ */
+export function generateStealthAddress({
+    viewingPublicKey,
+    spendingPublicKey,
+    ephemeralPrivateKey
+}: {
+    viewingPublicKey: Hex
+    spendingPublicKey: Hex
+    ephemeralPrivateKey: Hex
+}): Address {
+    const hashedSharedSecret = computeSharedSecret({
+        privateKey: ephemeralPrivateKey,
+        publicKey: viewingPublicKey
+    })
+
+    const stealthPublicKey = getStealthPublicKey({ spendingPublicKey, hashedSharedSecret })
+
+    return publicKeyToAddress(stealthPublicKey)
+}

package/src/stealthAddresses/generateStealthPrivateKey.ts

@@ -0,0 +1,29 @@
+import { secp256k1 } from "@noble/curves/secp256k1"
+import { bytesToNumberBE, numberToBytesBE } from "@noble/curves/utils"
+import { Hex } from "../types"
+import { bytesToHex, hexToBytes } from "../bytes"
+import { computeSharedSecret } from "./computeSharedSecret"
+
+/**
+ * Recovers the private key controlling a stealth address,
+ * (p_spend + s_h) mod n.
+ */
+export function generateStealthPrivateKey({
+    ephemeralPublicKey,
+    viewingPrivateKey,
+    spendingPrivateKey
+}: {
+    ephemeralPublicKey: Hex
+    viewingPrivateKey: Hex
+    spendingPrivateKey: Hex
+}): Hex {
+    const secretHash = computeSharedSecret({
+        privateKey: viewingPrivateKey,
+        publicKey: ephemeralPublicKey
+    })
+
+    const privateKey =
+        (bytesToNumberBE(hexToBytes(spendingPrivateKey)) + bytesToNumberBE(secretHash)) % secp256k1.Point.CURVE().n
+
+    return bytesToHex(numberToBytesBE(privateKey, 32))
+}