@shroud-fi/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShroudFi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @shroud-fi/core
+
+> secp256k1 stealth-address identity layer for the ShroudFi privacy SDK.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/core.svg)](https://www.npmjs.com/package/@shroud-fi/core)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/core viem
+```
+
+## What it does
+
+`@shroud-fi/core` is the identity foundation every other ShroudFi package builds on.
+
+- **Deterministic identity** — derives an agent's stealth meta-address (`(spendPub, scanPub)`) from a single 32-byte master seed.
+- **EIP-5564 / 6538 primitives** — canonical Base-network encoding of stealth meta-addresses (`st:base:0x…`), plus the secp256k1 ops used to derive one-time payment addresses.
+- **Constant-time + audited** — built on `@noble/curves` (Cure53-audited) and `@noble/hashes`. Zero new cryptographic surface.
+
+The same master seed yields the same meta-address whether you're using the SDK, the MCP server, or the REST API — so an agent's privacy identity is portable across runtimes.
+
+## Quick start
+
+```ts
+import { deriveAgentIdentity, encodeMetaAddress } from '@shroud-fi/core';
+
+const identity = deriveAgentIdentity('0x' + 'a'.repeat(64) /* master seed */);
+
+console.log(identity.metaAddressEncoded);
+// → st:base:0x024fa9bb…
+```
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `deriveAgentIdentity(seed)` | Domain-separated identity derivation from a master seed. |
+| `encodeMetaAddress(id)` | Encode spend + scan public keys into the canonical `st:base:0x…` wire format. |
+| `decodeMetaAddress(s)` | Parse `st:base:0x…` into spend + scan pubkeys. |
+| `AgentIdentity` | `{ spendPub, scanPub, metaAddressEncoded, deriveSpendingKey, deriveScanningKey }` |
+
+Full API reference: [shroudfi.live/sdk#core](https://shroudfi.live/sdk#core)
+
+## Privacy invariants
+
+- The **spending key never leaves agent runtime.** No serialization, no logging, no transmission.
+- The **scanning key is separable** — you can delegate it to a scanning service, but never log it alongside identity.
+- **No plaintext keys in error objects.** All `core` errors are structured + key-free.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/compute-key.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { ScanningKey, SpendingKey } from './types.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 declare function computeStealthKey(scanningKey: ScanningKey, spendingKey: SpendingKey, ephemeralPubKey: Uint8Array): Uint8Array;
+//# sourceMappingURL=compute-key.d.ts.map

package/dist/cjs/compute-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-key.d.ts","sourceRoot":"","sources":["../../src/compute-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,UAAU,GAC1B,UAAU,CA6BZ"}

package/dist/cjs/compute-key.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeStealthKey = computeStealthKey;
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const sha3_1 = require("@noble/hashes/sha3");
+const errors_js_1 = require("./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
+ */
+function computeStealthKey(scanningKey, spendingKey, ephemeralPubKey) {
+    // Validate ephemeral public key
+    let ephemeralPoint;
+    try {
+        ephemeralPoint = secp256k1_1.secp256k1.ProjectivePoint.fromHex(ephemeralPubKey);
+    }
+    catch {
+        throw new errors_js_1.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 = (0, sha3_1.keccak_256)(sharedSecretCompressed); // 32 bytes
+    // Step 3: Stealth private key = (spendingPriv + hashedSecret) mod n
+    const n = secp256k1_1.secp256k1.CURVE.n;
+    const spendScalar = bytesToBigInt(spendingKey.bytes);
+    const hashedScalar = bytesToBigInt(hashedSecret) % n;
+    const stealthScalar = (spendScalar + hashedScalar) % n;
+    if (stealthScalar === 0n) {
+        throw new errors_js_1.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) {
+    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, length) {
+    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;
+}
+//# sourceMappingURL=compute-key.js.map

package/dist/cjs/compute-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-key.js","sourceRoot":"","sources":["../../src/compute-key.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAiBH,8CAiCC;AAhDD,uDAAoD;AACpD,6CAAgD;AAEhD,2CAAmE;AAEnE;;;;;;;;;GASG;AACH,SAAgB,iBAAiB,CAC/B,WAAwB,EACxB,WAAwB,EACxB,eAA2B;IAE3B,gCAAgC;IAChC,IAAI,cAA8D,CAAC;IACnE,IAAI,CAAC;QACH,cAAc,GAAG,qBAAS,CAAC,eAAe,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,2BAAe,CAAC,8BAA8B,CAAC,CAAC;IAC5D,CAAC;IAED,6DAA6D;IAC7D,MAAM,UAAU,GAAG,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,iBAAiB,GAAG,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAE9D,4CAA4C;IAC5C,MAAM,sBAAsB,GAAG,iBAAiB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW;IAC9E,MAAM,YAAY,GAAG,IAAA,iBAAU,EAAC,sBAAsB,CAAC,CAAC,CAAC,WAAW;IAEpE,oEAAoE;IACpE,MAAM,CAAC,GAAG,qBAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5B,MAAM,WAAW,GAAG,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,aAAa,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAEvD,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,+BAAmB,CAAC,6BAA6B,CAAC,CAAC;IAC/D,CAAC;IAED,yDAAyD;IACzD,OAAO,aAAa,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,qDAAqD;AACrD,SAAS,aAAa,CAAC,KAAiB;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kEAAkE;AAClE,SAAS,aAAa,CAAC,KAAa,EAAE,MAAc;IAClD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC;QACtC,SAAS,KAAK,EAAE,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cjs/constants.d.ts

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

package/dist/cjs/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oDAAoD;AACpD,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,SAAS,oBAAoB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EACpC,4CAAqD,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EACnC,4CAAqD,CAAC"}

package/dist/cjs/constants.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * ShroudFi Core Constants
+ *
+ * EIP-5564 / ERC-6538 scheme configuration for Base (EVM).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC6538_REGISTRY_ADDRESS = exports.ERC5564_ANNOUNCER_ADDRESS = exports.HKDF_SALT = exports.SCHEME_ID = void 0;
+/** EIP-5564 scheme ID for secp256k1 + view tags. */
+exports.SCHEME_ID = 1;
+/** HKDF salt used for all key derivation from master seed. */
+exports.HKDF_SALT = 'ShroudFi-EVM-v1';
+/**
+ * ERC-5564 Announcer singleton address.
+ * Deterministic CREATE2 deployment -- same address on every EVM chain including Base.
+ */
+exports.ERC5564_ANNOUNCER_ADDRESS = '0x55649E01B5Df198D18D95b5cc5051630cfD45564';
+/**
+ * ERC-6538 Stealth Meta-Address Registry singleton address.
+ * Deterministic CREATE2 deployment -- same address on every EVM chain including Base.
+ */
+exports.ERC6538_REGISTRY_ADDRESS = '0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538';
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,oDAAoD;AACvC,QAAA,SAAS,GAAG,CAAC,CAAC;AAE3B,8DAA8D;AACjD,QAAA,SAAS,GAAG,iBAAiB,CAAC;AAE3C;;;GAGG;AACU,QAAA,yBAAyB,GACpC,4CAAqD,CAAC;AAExD;;;GAGG;AACU,QAAA,wBAAwB,GACnC,4CAAqD,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare class ShroudFiError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown when a private or public key fails validation. */
+export declare class InvalidKeyError extends ShroudFiError {
+    constructor(message?: string);
+}
+/** Thrown when a stealth meta-address cannot be parsed or is malformed. */
+export declare class InvalidMetaAddressError extends ShroudFiError {
+    constructor(message?: string);
+}
+/** Thrown when stealth address generation or verification fails. */
+export declare class StealthAddressError extends ShroudFiError {
+    constructor(message?: string);
+}
+/** 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;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8CAA8C;AAC9C,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1C;AAED,4DAA4D;AAC5D,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,GAAE,MAA+B;CAIrD;AAED,2EAA2E;AAC3E,qBAAa,uBAAwB,SAAQ,aAAa;gBAC5C,OAAO,GAAE,MAAuC;CAI7D;AAED,oEAAoE;AACpE,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,OAAO,GAAE,MAA2C;CAIjE;AAED,mFAAmF;AACnF,MAAM,MAAM,MAAM,CAAC,CAAC,IAChB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC"}

package/dist/cjs/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StealthAddressError = exports.InvalidMetaAddressError = exports.InvalidKeyError = exports.ShroudFiError = void 0;
+/** Base error for all ShroudFi operations. */
+class ShroudFiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ShroudFiError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.ShroudFiError = ShroudFiError;
+/** Thrown when a private or public key fails validation. */
+class InvalidKeyError extends ShroudFiError {
+    constructor(message = 'Invalid key material') {
+        super('INVALID_KEY', message);
+        this.name = 'InvalidKeyError';
+    }
+}
+exports.InvalidKeyError = InvalidKeyError;
+/** Thrown when a stealth meta-address cannot be parsed or is malformed. */
+class InvalidMetaAddressError extends ShroudFiError {
+    constructor(message = 'Invalid stealth meta-address') {
+        super('INVALID_META_ADDRESS', message);
+        this.name = 'InvalidMetaAddressError';
+    }
+}
+exports.InvalidMetaAddressError = InvalidMetaAddressError;
+/** Thrown when stealth address generation or verification fails. */
+class StealthAddressError extends ShroudFiError {
+    constructor(message = 'Stealth address operation failed') {
+        super('STEALTH_ADDRESS_ERROR', message);
+        this.name = 'StealthAddressError';
+    }
+}
+exports.StealthAddressError = StealthAddressError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,8CAA8C;AAC9C,MAAa,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AATD,sCASC;AAED,4DAA4D;AAC5D,MAAa,eAAgB,SAAQ,aAAa;IAChD,YAAY,UAAkB,sBAAsB;QAClD,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,2EAA2E;AAC3E,MAAa,uBAAwB,SAAQ,aAAa;IACxD,YAAY,UAAkB,8BAA8B;QAC1D,KAAK,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AALD,0DAKC;AAED,oEAAoE;AACpE,MAAa,mBAAoB,SAAQ,aAAa;IACpD,YAAY,UAAkB,kCAAkC;QAC9D,KAAK,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AALD,kDAKC"}

package/dist/cjs/identity.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 type { KeyHierarchy, StealthMetaAddress } from './types.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 declare function createAgentIdentity(masterSeed?: Uint8Array): AgentIdentity;
+//# sourceMappingURL=identity.d.ts.map

package/dist/cjs/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAInE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,aAAa,CAmB1E"}

package/dist/cjs/identity.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentIdentity = createAgentIdentity;
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const utils_1 = require("@noble/hashes/utils");
+const keys_js_1 = require("./keys.js");
+const constants_js_1 = require("./constants.js");
+/**
+ * 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
+ */
+function createAgentIdentity(masterSeed) {
+    const seed = masterSeed ?? (0, utils_1.randomBytes)(32);
+    const keys = (0, keys_js_1.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_1.secp256k1.getPublicKey(keys.spendingKey.bytes, true);
+    const viewingPubKey = secp256k1_1.secp256k1.getPublicKey(keys.scanningKey.bytes, true);
+    const metaAddress = {
+        spendingPubKey,
+        viewingPubKey,
+        schemeId: constants_js_1.SCHEME_ID,
+    };
+    return { keys, metaAddress };
+}
+//# sourceMappingURL=identity.js.map

package/dist/cjs/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAmBH,kDAmBC;AApCD,uDAAoD;AACpD,+CAAkD;AAElD,uCAAuC;AACvC,iDAA2C;AAO3C;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,UAAuB;IACzD,MAAM,IAAI,GAAG,UAAU,IAAI,IAAA,mBAAW,EAAC,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAA,oBAAU,EAAC,IAAI,CAAC,CAAC;IAE9B,uDAAuD;IACvD,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,gEAAgE;IAChE,MAAM,cAAc,GAAG,qBAAS,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5E,MAAM,aAAa,GAAG,qBAAS,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAE3E,MAAM,WAAW,GAAuB;QACtC,cAAc;QACd,aAAa;QACb,QAAQ,EAAE,wBAAS;KACpB,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,12 @@
+export type { SpendingKey, ScanningKey, ViewingKey, StealthMetaAddress, StealthAddressResult, KeyHierarchy, } from './types.js';
+export { ShroudFiError, InvalidKeyError, InvalidMetaAddressError, StealthAddressError, } from './errors.js';
+export type { Result } from './errors.js';
+export { SCHEME_ID, HKDF_SALT, ERC5564_ANNOUNCER_ADDRESS, ERC6538_REGISTRY_ADDRESS, } from './constants.js';
+export { deriveKeys } from './keys.js';
+export { generateStealthAddress } from './stealth.js';
+export { computeStealthKey } from './compute-key.js';
+export { extractViewTag, checkViewTag } from './view-tag.js';
+export { encodeMetaAddress, decodeMetaAddress } from './meta-address.js';
+export { createAgentIdentity } from './identity.js';
+export type { AgentIdentity } from './identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EACL,SAAS,EACT,SAAS,EACT,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentIdentity = exports.decodeMetaAddress = exports.encodeMetaAddress = exports.checkViewTag = exports.extractViewTag = exports.computeStealthKey = exports.generateStealthAddress = exports.deriveKeys = exports.ERC6538_REGISTRY_ADDRESS = exports.ERC5564_ANNOUNCER_ADDRESS = exports.HKDF_SALT = exports.SCHEME_ID = exports.StealthAddressError = exports.InvalidMetaAddressError = exports.InvalidKeyError = exports.ShroudFiError = void 0;
+// Errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ShroudFiError", { enumerable: true, get: function () { return errors_js_1.ShroudFiError; } });
+Object.defineProperty(exports, "InvalidKeyError", { enumerable: true, get: function () { return errors_js_1.InvalidKeyError; } });
+Object.defineProperty(exports, "InvalidMetaAddressError", { enumerable: true, get: function () { return errors_js_1.InvalidMetaAddressError; } });
+Object.defineProperty(exports, "StealthAddressError", { enumerable: true, get: function () { return errors_js_1.StealthAddressError; } });
+// Constants
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "SCHEME_ID", { enumerable: true, get: function () { return constants_js_1.SCHEME_ID; } });
+Object.defineProperty(exports, "HKDF_SALT", { enumerable: true, get: function () { return constants_js_1.HKDF_SALT; } });
+Object.defineProperty(exports, "ERC5564_ANNOUNCER_ADDRESS", { enumerable: true, get: function () { return constants_js_1.ERC5564_ANNOUNCER_ADDRESS; } });
+Object.defineProperty(exports, "ERC6538_REGISTRY_ADDRESS", { enumerable: true, get: function () { return constants_js_1.ERC6538_REGISTRY_ADDRESS; } });
+// Key derivation
+var keys_js_1 = require("./keys.js");
+Object.defineProperty(exports, "deriveKeys", { enumerable: true, get: function () { return keys_js_1.deriveKeys; } });
+// Stealth address generation (sender side)
+var stealth_js_1 = require("./stealth.js");
+Object.defineProperty(exports, "generateStealthAddress", { enumerable: true, get: function () { return stealth_js_1.generateStealthAddress; } });
+// Stealth key computation (recipient side)
+var compute_key_js_1 = require("./compute-key.js");
+Object.defineProperty(exports, "computeStealthKey", { enumerable: true, get: function () { return compute_key_js_1.computeStealthKey; } });
+// View tag utilities
+var view_tag_js_1 = require("./view-tag.js");
+Object.defineProperty(exports, "extractViewTag", { enumerable: true, get: function () { return view_tag_js_1.extractViewTag; } });
+Object.defineProperty(exports, "checkViewTag", { enumerable: true, get: function () { return view_tag_js_1.checkViewTag; } });
+// Meta-address encode/decode
+var meta_address_js_1 = require("./meta-address.js");
+Object.defineProperty(exports, "encodeMetaAddress", { enumerable: true, get: function () { return meta_address_js_1.encodeMetaAddress; } });
+Object.defineProperty(exports, "decodeMetaAddress", { enumerable: true, get: function () { return meta_address_js_1.decodeMetaAddress; } });
+// Agent identity factory
+var identity_js_1 = require("./identity.js");
+Object.defineProperty(exports, "createAgentIdentity", { enumerable: true, get: function () { return identity_js_1.createAgentIdentity; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAUA,SAAS;AACT,yCAKqB;AAJnB,0GAAA,aAAa,OAAA;AACb,4GAAA,eAAe,OAAA;AACf,oHAAA,uBAAuB,OAAA;AACvB,gHAAA,mBAAmB,OAAA;AAIrB,YAAY;AACZ,+CAKwB;AAJtB,yGAAA,SAAS,OAAA;AACT,yGAAA,SAAS,OAAA;AACT,yHAAA,yBAAyB,OAAA;AACzB,wHAAA,wBAAwB,OAAA;AAG1B,iBAAiB;AACjB,qCAAuC;AAA9B,qGAAA,UAAU,OAAA;AAEnB,2CAA2C;AAC3C,2CAAsD;AAA7C,oHAAA,sBAAsB,OAAA;AAE/B,2CAA2C;AAC3C,mDAAqD;AAA5C,mHAAA,iBAAiB,OAAA;AAE1B,qBAAqB;AACrB,6CAA6D;AAApD,6GAAA,cAAc,OAAA;AAAE,2GAAA,YAAY,OAAA;AAErC,6BAA6B;AAC7B,qDAAyE;AAAhE,oHAAA,iBAAiB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAE7C,yBAAyB;AACzB,6CAAoD;AAA3C,kHAAA,mBAAmB,OAAA"}

package/dist/cjs/keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { KeyHierarchy } from './types.js';
+/**
+ * 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 declare function deriveKeys(masterSeed: Uint8Array): KeyHierarchy;
+//# sourceMappingURL=keys.d.ts.map

package/dist/cjs/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAwC,MAAM,YAAY,CAAC;AAiBrF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAmB/D"}

package/dist/cjs/keys.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveKeys = deriveKeys;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const errors_js_1 = require("./errors.js");
+const constants_js_1 = require("./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, label) {
+    if (bytes.length !== 32) {
+        throw new errors_js_1.InvalidKeyError(`Derived ${label} has invalid length`);
+    }
+    if (!secp256k1_1.secp256k1.utils.isValidPrivateKey(bytes)) {
+        throw new errors_js_1.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
+ */
+function deriveKeys(masterSeed) {
+    if (masterSeed.length !== 32) {
+        throw new errors_js_1.InvalidKeyError('Master seed must be exactly 32 bytes');
+    }
+    const spendingBytes = (0, hkdf_1.hkdf)(sha256_1.sha256, masterSeed, constants_js_1.HKDF_SALT, 'spending-key', 32);
+    assertValidScalar(spendingBytes, 'spending key');
+    const scanningBytes = (0, hkdf_1.hkdf)(sha256_1.sha256, masterSeed, constants_js_1.HKDF_SALT, 'scanning-key', 32);
+    assertValidScalar(scanningBytes, 'scanning key');
+    const viewingBytes = (0, hkdf_1.hkdf)(sha256_1.sha256, masterSeed, constants_js_1.HKDF_SALT, 'viewing-key', 32);
+    assertValidScalar(viewingBytes, 'viewing key');
+    return {
+        spendingKey: { __brand: 'SpendingKey', bytes: spendingBytes },
+        scanningKey: { __brand: 'ScanningKey', bytes: scanningBytes },
+        viewingKey: { __brand: 'ViewingKey', bytes: viewingBytes },
+    };
+}
+//# sourceMappingURL=keys.js.map

package/dist/cjs/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/keys.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AA6BH,gCAmBC;AA9CD,6CAA0C;AAC1C,iDAA8C;AAC9C,uDAAoD;AAEpD,2CAA8C;AAC9C,iDAA2C;AAE3C;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAiB,EAAE,KAAa;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,2BAAe,CAAC,WAAW,KAAK,qBAAqB,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,qBAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,2BAAe,CAAC,WAAW,KAAK,kCAAkC,CAAC,CAAC;IAChF,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,UAAsB;IAC/C,IAAI,UAAU,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,2BAAe,CAAC,sCAAsC,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,aAAa,GAAG,IAAA,WAAI,EAAC,eAAM,EAAE,UAAU,EAAE,wBAAS,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IAC9E,iBAAiB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAEjD,MAAM,aAAa,GAAG,IAAA,WAAI,EAAC,eAAM,EAAE,UAAU,EAAE,wBAAS,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IAC9E,iBAAiB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAEjD,MAAM,YAAY,GAAG,IAAA,WAAI,EAAC,eAAM,EAAE,UAAU,EAAE,wBAAS,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;IAC5E,iBAAiB,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IAE/C,OAAO;QACL,WAAW,EAAE,EAAE,OAAO,EAAE,aAAsB,EAAE,KAAK,EAAE,aAAa,EAAiB;QACrF,WAAW,EAAE,EAAE,OAAO,EAAE,aAAsB,EAAE,KAAK,EAAE,aAAa,EAAiB;QACrF,UAAU,EAAE,EAAE,OAAO,EAAE,YAAqB,EAAE,KAAK,EAAE,YAAY,EAAgB;KAClF,CAAC;AACJ,CAAC"}

package/dist/cjs/meta-address.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { StealthMetaAddress } from './types.js';
+/**
+ * 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 declare function encodeMetaAddress(meta: StealthMetaAddress): string;
+/**
+ * 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 declare function decodeMetaAddress(encoded: string): StealthMetaAddress;
+//# sourceMappingURL=meta-address.d.ts.map

package/dist/cjs/meta-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-address.d.ts","sourceRoot":"","sources":["../../src/meta-address.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgCrD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAQlE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAiCrE"}