@shroud-fi/core 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "secp256k1 stealth-address identity layer for the ShroudFi privacy SDK. EIP-5564/6538 primitives every other package builds on.",
   "keywords": [
     "shroudfi",
@@ -28,7 +28,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "@noble/curves": "^1.6.0",
@@ -41,7 +44,7 @@
     "viem": "^2.21.0",
     "vitest": "^2.0.0",
     "typescript": "^5.6.0",
-    "@shroud-fi/transport": "0.1.3"
+    "@shroud-fi/transport": "0.1.4"
   },
   "publishConfig": {
     "access": "public"

package/src/compute-key.ts

@@ -0,0 +1,81 @@
+/**
+ * Stealth Key Computation (Recipient Side)
+ *
+ * Given the scanning private key, spending private key, and the
+ * ephemeral public key from an announcement, derive the stealth
+ * private key that controls the stealth address.
+ *
+ *   1. ECDH: sharedSecret = scanningPrivKey * ephemeralPubKey
+ *   2. Hash: hashedSecret = keccak256(compress(sharedSecret))
+ *   3. Stealth private key: p_stealth = (spendingPrivKey + hashedSecret) mod n
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { keccak_256 } from '@noble/hashes/sha3';
+import type { ScanningKey, SpendingKey } from './types.js';
+import { InvalidKeyError, StealthAddressError } from './errors.js';
+
+/**
+ * Compute the stealth private key for a detected payment.
+ *
+ * @param scanningKey - Recipient's scanning private key
+ * @param spendingKey - Recipient's spending private key
+ * @param ephemeralPubKey - Ephemeral public key from the announcement (33 bytes compressed)
+ * @returns 32-byte stealth private key
+ * @throws InvalidKeyError if ephemeral public key is invalid
+ * @throws StealthAddressError if the derived stealth key is invalid
+ */
+export function computeStealthKey(
+  scanningKey: ScanningKey,
+  spendingKey: SpendingKey,
+  ephemeralPubKey: Uint8Array,
+): Uint8Array {
+  // Validate ephemeral public key
+  let ephemeralPoint: InstanceType<typeof secp256k1.ProjectivePoint>;
+  try {
+    ephemeralPoint = secp256k1.ProjectivePoint.fromHex(ephemeralPubKey);
+  } catch {
+    throw new InvalidKeyError('Invalid ephemeral public key');
+  }
+
+  // Step 1: ECDH shared secret  S = scanningPriv * P_ephemeral
+  const scanScalar = bytesToBigInt(scanningKey.bytes);
+  const sharedSecretPoint = ephemeralPoint.multiply(scanScalar);
+
+  // Step 2: Hash the compressed shared secret
+  const sharedSecretCompressed = sharedSecretPoint.toRawBytes(true); // 33 bytes
+  const hashedSecret = keccak_256(sharedSecretCompressed); // 32 bytes
+
+  // Step 3: Stealth private key = (spendingPriv + hashedSecret) mod n
+  const n = secp256k1.CURVE.n;
+  const spendScalar = bytesToBigInt(spendingKey.bytes);
+  const hashedScalar = bytesToBigInt(hashedSecret) % n;
+  const stealthScalar = (spendScalar + hashedScalar) % n;
+
+  if (stealthScalar === 0n) {
+    throw new StealthAddressError('Derived stealth key is zero');
+  }
+
+  // Convert BigInt back to 32-byte Uint8Array (big-endian)
+  return bigIntToBytes(stealthScalar, 32);
+}
+
+/** Convert a Uint8Array to a BigInt (big-endian). */
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (const byte of bytes) {
+    result = (result << 8n) | BigInt(byte);
+  }
+  return result;
+}
+
+/** Convert a BigInt to a fixed-length Uint8Array (big-endian). */
+function bigIntToBytes(value: bigint, length: number): Uint8Array {
+  const result = new Uint8Array(length);
+  let remaining = value;
+  for (let i = length - 1; i >= 0; i--) {
+    result[i] = Number(remaining & 0xffn);
+    remaining >>= 8n;
+  }
+  return result;
+}

package/src/constants.ts

@@ -0,0 +1,25 @@
+/**
+ * ShroudFi Core Constants
+ *
+ * EIP-5564 / ERC-6538 scheme configuration for Base (EVM).
+ */
+
+/** EIP-5564 scheme ID for secp256k1 + view tags. */
+export const SCHEME_ID = 1;
+
+/** HKDF salt used for all key derivation from master seed. */
+export const HKDF_SALT = 'ShroudFi-EVM-v1';
+
+/**
+ * ERC-5564 Announcer singleton address.
+ * Deterministic CREATE2 deployment -- same address on every EVM chain including Base.
+ */
+export const ERC5564_ANNOUNCER_ADDRESS =
+  '0x55649E01B5Df198D18D95b5cc5051630cfD45564' as const;
+
+/**
+ * ERC-6538 Stealth Meta-Address Registry singleton address.
+ * Deterministic CREATE2 deployment -- same address on every EVM chain including Base.
+ */
+export const ERC6538_REGISTRY_ADDRESS =
+  '0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538' as const;

package/src/errors.ts

@@ -0,0 +1,50 @@
+/**
+ * ShroudFi Privacy-Safe Error Hierarchy
+ *
+ * Rules:
+ * - NEVER include private keys, seeds, or scalars in error messages.
+ * - NEVER include amounts or balances.
+ * - NEVER include stealth addresses or ephemeral keys.
+ * - Safe to include: error codes, generic descriptions.
+ */
+
+/** Base error for all ShroudFi operations. */
+export class ShroudFiError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'ShroudFiError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** Thrown when a private or public key fails validation. */
+export class InvalidKeyError extends ShroudFiError {
+  constructor(message: string = 'Invalid key material') {
+    super('INVALID_KEY', message);
+    this.name = 'InvalidKeyError';
+  }
+}
+
+/** Thrown when a stealth meta-address cannot be parsed or is malformed. */
+export class InvalidMetaAddressError extends ShroudFiError {
+  constructor(message: string = 'Invalid stealth meta-address') {
+    super('INVALID_META_ADDRESS', message);
+    this.name = 'InvalidMetaAddressError';
+  }
+}
+
+/** Thrown when stealth address generation or verification fails. */
+export class StealthAddressError extends ShroudFiError {
+  constructor(message: string = 'Stealth address operation failed') {
+    super('STEALTH_ADDRESS_ERROR', message);
+    this.name = 'StealthAddressError';
+  }
+}
+
+/** Discriminated union result type -- avoids throwing for sensitive operations. */
+export type Result<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: ShroudFiError };

package/src/identity.ts

@@ -0,0 +1,45 @@
+/**
+ * Agent Identity Factory
+ *
+ * Creates a complete ShroudFi agent identity (key hierarchy + meta-address)
+ * from an optional master seed. If no seed is provided, generates 32
+ * cryptographically random bytes via crypto.getRandomValues.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { randomBytes } from '@noble/hashes/utils';
+import type { KeyHierarchy, StealthMetaAddress } from './types.js';
+import { deriveKeys } from './keys.js';
+import { SCHEME_ID } from './constants.js';
+
+export interface AgentIdentity {
+  readonly keys: KeyHierarchy;
+  readonly metaAddress: StealthMetaAddress;
+}
+
+/**
+ * Create a full agent identity with key hierarchy and meta-address.
+ *
+ * @param masterSeed - Optional 32-byte seed. If omitted, generates random bytes.
+ * @returns AgentIdentity with derived keys and meta-address
+ */
+export function createAgentIdentity(masterSeed?: Uint8Array): AgentIdentity {
+  const seed = masterSeed ?? randomBytes(32);
+  const keys = deriveKeys(seed);
+
+  // Derive compressed public keys from the private keys.
+  // EIP-5564 scheme 1 has only spending + viewing keys, where "viewing" is the
+  // key used for ECDH scanning. In the @shroud-fi/core hierarchy we name that
+  // ECDH-scan key `scanningKey` (its semantic role). The separate `viewingKey`
+  // is reserved for future compliance/delegated-disclosure flows.
+  const spendingPubKey = secp256k1.getPublicKey(keys.spendingKey.bytes, true);
+  const viewingPubKey = secp256k1.getPublicKey(keys.scanningKey.bytes, true);
+
+  const metaAddress: StealthMetaAddress = {
+    spendingPubKey,
+    viewingPubKey,
+    schemeId: SCHEME_ID,
+  };
+
+  return { keys, metaAddress };
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Types
+export type {
+  SpendingKey,
+  ScanningKey,
+  ViewingKey,
+  StealthMetaAddress,
+  StealthAddressResult,
+  KeyHierarchy,
+} from './types.js';
+
+// Errors
+export {
+  ShroudFiError,
+  InvalidKeyError,
+  InvalidMetaAddressError,
+  StealthAddressError,
+} from './errors.js';
+export type { Result } from './errors.js';
+
+// Constants
+export {
+  SCHEME_ID,
+  HKDF_SALT,
+  ERC5564_ANNOUNCER_ADDRESS,
+  ERC6538_REGISTRY_ADDRESS,
+} from './constants.js';
+
+// Key derivation
+export { deriveKeys } from './keys.js';
+
+// Stealth address generation (sender side)
+export { generateStealthAddress } from './stealth.js';
+
+// Stealth key computation (recipient side)
+export { computeStealthKey } from './compute-key.js';
+
+// View tag utilities
+export { extractViewTag, checkViewTag } from './view-tag.js';
+
+// Meta-address encode/decode
+export { encodeMetaAddress, decodeMetaAddress } from './meta-address.js';
+
+// Agent identity factory
+export { createAgentIdentity } from './identity.js';
+export type { AgentIdentity } from './identity.js';

package/src/keys.ts

@@ -0,0 +1,55 @@
+/**
+ * Key Derivation -- HKDF-SHA256
+ *
+ * Derives a full KeyHierarchy from a 32-byte master seed using
+ * HKDF with domain-separated info labels. Each derived key is
+ * validated as a valid secp256k1 scalar (1 < k < n).
+ */
+
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import type { KeyHierarchy, SpendingKey, ScanningKey, ViewingKey } from './types.js';
+import { InvalidKeyError } from './errors.js';
+import { HKDF_SALT } from './constants.js';
+
+/**
+ * Validate that a 32-byte array is a valid secp256k1 private key scalar.
+ * Must satisfy: 1 <= k < n  (curve order).
+ */
+function assertValidScalar(bytes: Uint8Array, label: string): void {
+  if (bytes.length !== 32) {
+    throw new InvalidKeyError(`Derived ${label} has invalid length`);
+  }
+  if (!secp256k1.utils.isValidPrivateKey(bytes)) {
+    throw new InvalidKeyError(`Derived ${label} is not a valid secp256k1 scalar`);
+  }
+}
+
+/**
+ * Derive the full ShroudFi key hierarchy from a master seed.
+ *
+ * @param masterSeed - 32-byte cryptographically random seed
+ * @returns KeyHierarchy with spending, scanning, and viewing keys
+ * @throws InvalidKeyError if seed length is wrong or a derived key is invalid
+ */
+export function deriveKeys(masterSeed: Uint8Array): KeyHierarchy {
+  if (masterSeed.length !== 32) {
+    throw new InvalidKeyError('Master seed must be exactly 32 bytes');
+  }
+
+  const spendingBytes = hkdf(sha256, masterSeed, HKDF_SALT, 'spending-key', 32);
+  assertValidScalar(spendingBytes, 'spending key');
+
+  const scanningBytes = hkdf(sha256, masterSeed, HKDF_SALT, 'scanning-key', 32);
+  assertValidScalar(scanningBytes, 'scanning key');
+
+  const viewingBytes = hkdf(sha256, masterSeed, HKDF_SALT, 'viewing-key', 32);
+  assertValidScalar(viewingBytes, 'viewing key');
+
+  return {
+    spendingKey: { __brand: 'SpendingKey' as const, bytes: spendingBytes } as SpendingKey,
+    scanningKey: { __brand: 'ScanningKey' as const, bytes: scanningBytes } as ScanningKey,
+    viewingKey: { __brand: 'ViewingKey' as const, bytes: viewingBytes } as ViewingKey,
+  };
+}

package/src/meta-address.ts

@@ -0,0 +1,101 @@
+/**
+ * ERC-6538 Stealth Meta-Address Encode/Decode
+ *
+ * Format: st:base:0x<spendingPubKey 33 bytes hex><viewingPubKey 33 bytes hex>
+ *
+ * Both keys are SEC1 compressed secp256k1 public keys (prefix 0x02 or 0x03).
+ * Total raw payload: 66 bytes = 132 hex characters.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import type { StealthMetaAddress } from './types.js';
+import { InvalidMetaAddressError } from './errors.js';
+import { SCHEME_ID } from './constants.js';
+
+const META_ADDRESS_PREFIX = 'st:base:0x';
+const COMPRESSED_KEY_LENGTH = 33; // bytes
+const TOTAL_PAYLOAD_LENGTH = COMPRESSED_KEY_LENGTH * 2; // 66 bytes
+
+/**
+ * Validate that a byte array is a valid compressed secp256k1 public key.
+ * Must be 33 bytes with 0x02 or 0x03 prefix.
+ */
+function assertValidCompressedKey(key: Uint8Array, label: string): void {
+  if (key.length !== COMPRESSED_KEY_LENGTH) {
+    throw new InvalidMetaAddressError(
+      `${label} must be ${COMPRESSED_KEY_LENGTH} bytes, got ${key.length}`,
+    );
+  }
+  const prefix = key[0];
+  if (prefix !== 0x02 && prefix !== 0x03) {
+    throw new InvalidMetaAddressError(
+      `${label} must have 0x02 or 0x03 prefix`,
+    );
+  }
+  // Validate it's actually on the curve
+  try {
+    secp256k1.ProjectivePoint.fromHex(key);
+  } catch {
+    throw new InvalidMetaAddressError(`${label} is not a valid secp256k1 point`);
+  }
+}
+
+/**
+ * Encode a StealthMetaAddress into the ERC-6538 URI format.
+ *
+ * @param meta - Stealth meta-address containing spending and viewing public keys
+ * @returns Encoded string: "st:base:0x<spendHex><viewHex>"
+ * @throws InvalidMetaAddressError if keys are invalid
+ */
+export function encodeMetaAddress(meta: StealthMetaAddress): string {
+  assertValidCompressedKey(meta.spendingPubKey, 'Spending public key');
+  assertValidCompressedKey(meta.viewingPubKey, 'Viewing public key');
+
+  const spendHex = bytesToHex(meta.spendingPubKey);
+  const viewHex = bytesToHex(meta.viewingPubKey);
+
+  return `${META_ADDRESS_PREFIX}${spendHex}${viewHex}`;
+}
+
+/**
+ * Decode an ERC-6538 URI string into a StealthMetaAddress.
+ *
+ * @param encoded - String in format "st:base:0x<66 bytes hex>"
+ * @returns Parsed StealthMetaAddress
+ * @throws InvalidMetaAddressError if format is invalid
+ */
+export function decodeMetaAddress(encoded: string): StealthMetaAddress {
+  if (!encoded.startsWith(META_ADDRESS_PREFIX)) {
+    throw new InvalidMetaAddressError(
+      `Meta-address must start with "${META_ADDRESS_PREFIX}"`,
+    );
+  }
+
+  const hexPayload = encoded.slice(META_ADDRESS_PREFIX.length);
+
+  if (hexPayload.length !== TOTAL_PAYLOAD_LENGTH * 2) {
+    throw new InvalidMetaAddressError(
+      `Meta-address hex payload must be ${TOTAL_PAYLOAD_LENGTH * 2} characters, got ${hexPayload.length}`,
+    );
+  }
+
+  let payloadBytes: Uint8Array;
+  try {
+    payloadBytes = hexToBytes(hexPayload);
+  } catch {
+    throw new InvalidMetaAddressError('Meta-address contains invalid hex characters');
+  }
+
+  const spendingPubKey = payloadBytes.slice(0, COMPRESSED_KEY_LENGTH);
+  const viewingPubKey = payloadBytes.slice(COMPRESSED_KEY_LENGTH);
+
+  assertValidCompressedKey(spendingPubKey, 'Spending public key');
+  assertValidCompressedKey(viewingPubKey, 'Viewing public key');
+
+  return {
+    spendingPubKey,
+    viewingPubKey,
+    schemeId: SCHEME_ID,
+  };
+}

package/src/stealth.ts

@@ -0,0 +1,107 @@
+/**
+ * Stealth Address Generation (Sender Side)
+ *
+ * Implements EIP-5564 scheme 1 (secp256k1):
+ *   1. Generate random ephemeral key r, compute R = r*G
+ *   2. ECDH: sharedSecret = r * viewingPubKey
+ *   3. Hash: hashedSecret = keccak256(compress(sharedSecret))
+ *   4. View tag: viewTag = hashedSecret[0]
+ *   5. Stealth pubkey: P_stealth = spendingPubKey + hashedSecret * G
+ *   6. Stealth address: keccak256(uncompressed64(P_stealth))[12:] -> 20-byte address
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { bytesToHex } from '@noble/hashes/utils';
+import type { StealthMetaAddress, StealthAddressResult } from './types.js';
+import { StealthAddressError, InvalidKeyError } from './errors.js';
+
+/**
+ * Convert a 64-byte uncompressed public key (no 0x04 prefix) to an EVM address.
+ * address = last 20 bytes of keccak256(pubkey64)
+ */
+function pubKeyToAddress(uncompressed64: Uint8Array): `0x${string}` {
+  const hash = keccak_256(uncompressed64);
+  const addrBytes = hash.slice(12);
+  return `0x${bytesToHex(addrBytes)}` as `0x${string}`;
+}
+
+/**
+ * Generate a one-time stealth address for a recipient.
+ *
+ * @param meta - Recipient's stealth meta-address (two compressed public keys)
+ * @returns StealthAddressResult with stealth address, ephemeral pubkey, and view tag
+ * @throws InvalidKeyError if meta-address public keys are invalid
+ * @throws StealthAddressError if the derived stealth point is at infinity
+ */
+export function generateStealthAddress(
+  meta: StealthMetaAddress,
+): StealthAddressResult {
+  // Validate input public keys by parsing them (fromHex validates on-curve)
+  let viewingPoint: InstanceType<typeof secp256k1.ProjectivePoint>;
+  let spendingPoint: InstanceType<typeof secp256k1.ProjectivePoint>;
+  try {
+    viewingPoint = secp256k1.ProjectivePoint.fromHex(meta.viewingPubKey);
+  } catch {
+    throw new InvalidKeyError('Invalid viewing public key in meta-address');
+  }
+  try {
+    spendingPoint = secp256k1.ProjectivePoint.fromHex(meta.spendingPubKey);
+  } catch {
+    throw new InvalidKeyError('Invalid spending public key in meta-address');
+  }
+
+  // Step 1: Generate ephemeral keypair
+  const ephemeralPriv = secp256k1.utils.randomPrivateKey();
+  const ephemeralPub = secp256k1.getPublicKey(ephemeralPriv, true); // compressed
+
+  try {
+    // Step 2: ECDH shared secret  S = r * P_view
+    const ephemeralScalar = bytesToBigInt(ephemeralPriv);
+    const sharedSecretPoint = viewingPoint.multiply(ephemeralScalar);
+
+    // Step 3: Hash the compressed shared secret
+    const sharedSecretCompressed = sharedSecretPoint.toRawBytes(true); // 33 bytes
+    const hashedSecret = keccak_256(sharedSecretCompressed); // 32 bytes
+
+    // Step 4: View tag = first byte
+    const viewTag = hashedSecret[0]!;
+
+    // Step 5: Stealth public key = P_spend + hashedSecret * G
+    const hashedScalar = bytesToBigInt(hashedSecret) % secp256k1.CURVE.n;
+    if (hashedScalar === 0n) {
+      throw new StealthAddressError('Hashed secret reduced to zero');
+    }
+    const hashedPoint = secp256k1.ProjectivePoint.BASE.multiply(hashedScalar);
+    const stealthPubPoint = spendingPoint.add(hashedPoint);
+
+    // Verify not point at infinity
+    try {
+      stealthPubPoint.assertValidity();
+    } catch {
+      throw new StealthAddressError('Stealth public key is the point at infinity');
+    }
+
+    // Step 6: Derive EVM address from uncompressed stealth public key
+    const stealthPubUncompressed = stealthPubPoint.toRawBytes(false); // 65 bytes (04 || x || y)
+    const stealthAddress = pubKeyToAddress(stealthPubUncompressed.slice(1)); // strip 0x04 prefix
+
+    return {
+      stealthAddress,
+      ephemeralPubKey: ephemeralPub,
+      viewTag,
+    };
+  } finally {
+    // Zero ephemeral private key
+    ephemeralPriv.fill(0);
+  }
+}
+
+/** Convert a Uint8Array to a BigInt (big-endian). */
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (const byte of bytes) {
+    result = (result << 8n) | BigInt(byte);
+  }
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * ShroudFi Core Types
+ *
+ * Branded key types for compile-time safety -- prevents accidentally
+ * passing a scanning key where a spending key is expected.
+ */
+
+/** secp256k1 spending private key (32 bytes). Controls funds. */
+export type SpendingKey = {
+  readonly __brand: 'SpendingKey';
+  readonly bytes: Uint8Array;
+};
+
+/** secp256k1 scanning private key (32 bytes). Detects incoming payments. */
+export type ScanningKey = {
+  readonly __brand: 'ScanningKey';
+  readonly bytes: Uint8Array;
+};
+
+/** secp256k1 viewing key (32 bytes). Enables selective disclosure. */
+export type ViewingKey = {
+  readonly __brand: 'ViewingKey';
+  readonly bytes: Uint8Array;
+};
+
+/**
+ * ERC-6538 stealth meta-address: two compressed secp256k1 public keys.
+ * Shareable -- contains NO private material.
+ */
+export interface StealthMetaAddress {
+  readonly spendingPubKey: Uint8Array; // 33 bytes compressed
+  readonly viewingPubKey: Uint8Array; // 33 bytes compressed
+  readonly schemeId: number;
+}
+
+/** Result of generating a one-time stealth address for a recipient. */
+export interface StealthAddressResult {
+  /** The derived stealth EVM address. */
+  readonly stealthAddress: `0x${string}`;
+  /** Compressed ephemeral public key (33 bytes) -- must be announced. */
+  readonly ephemeralPubKey: Uint8Array;
+  /** View tag (0-255) -- first byte of hashed shared secret. */
+  readonly viewTag: number;
+}
+
+/** Full key hierarchy derived from a master seed. */
+export interface KeyHierarchy {
+  readonly spendingKey: SpendingKey;
+  readonly scanningKey: ScanningKey;
+  readonly viewingKey: ViewingKey;
+}

package/src/view-tag.ts

@@ -0,0 +1,68 @@
+/**
+ * View Tag Utilities
+ *
+ * View tags enable fast filtering of stealth address announcements.
+ * The view tag is the first byte of keccak256(compress(ECDH_shared_secret)).
+ * This filters ~99.6% of non-matching announcements with a single byte check.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { keccak_256 } from '@noble/hashes/sha3';
+import type { ScanningKey } from './types.js';
+import { InvalidKeyError } from './errors.js';
+
+/**
+ * Extract the view tag from a compressed shared secret point.
+ * The view tag is byte 0 of keccak256(compressedPoint).
+ *
+ * @param sharedSecretCompressed - 33-byte compressed secp256k1 point
+ * @returns View tag value (0-255)
+ */
+export function extractViewTag(sharedSecretCompressed: Uint8Array): number {
+  const hash = keccak_256(sharedSecretCompressed);
+  return hash[0]!;
+}
+
+/**
+ * Check whether a view tag matches for a given scanning key and ephemeral public key.
+ *
+ * Performs the ECDH step and view tag extraction, then compares against
+ * the expected tag. This is the fast-path filter for scanning.
+ *
+ * @param scanningKey - Recipient's scanning private key
+ * @param ephemeralPubKey - Ephemeral public key from the announcement (33 bytes)
+ * @param expectedTag - The view tag from the announcement metadata
+ * @returns true if the view tag matches (candidate for full verification)
+ */
+export function checkViewTag(
+  scanningKey: ScanningKey,
+  ephemeralPubKey: Uint8Array,
+  expectedTag: number,
+): boolean {
+  // Validate ephemeral public key
+  let ephemeralPoint: InstanceType<typeof secp256k1.ProjectivePoint>;
+  try {
+    ephemeralPoint = secp256k1.ProjectivePoint.fromHex(ephemeralPubKey);
+  } catch {
+    throw new InvalidKeyError('Invalid ephemeral public key');
+  }
+
+  // ECDH: sharedSecret = scanningPriv * P_ephemeral
+  const scanScalar = bytesToBigInt(scanningKey.bytes);
+  const sharedSecretPoint = ephemeralPoint.multiply(scanScalar);
+
+  // Hash compressed shared secret and extract view tag
+  const sharedSecretCompressed = sharedSecretPoint.toRawBytes(true);
+  const tag = extractViewTag(sharedSecretCompressed);
+
+  return tag === expectedTag;
+}
+
+/** Convert a Uint8Array to a BigInt (big-endian). */
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (const byte of bytes) {
+    result = (result << 8n) | BigInt(byte);
+  }
+  return result;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "test", "node_modules"]
+}