@shroud-fi/agent-runtime 0.1.5 → 0.1.6

package/src/browser.ts

@@ -0,0 +1,126 @@
+/**
+ * createShroudAgentFromBrowserWallet — browser / EIP-1193 wallet entry point.
+ *
+ * Flow:
+ *   1. Ask the wallet to sign BROWSER_KEY_MESSAGE via personal_sign.
+ *   2. HKDF the signature bytes to a deterministic 32-byte master seed.
+ *   3. Delegate to createShroudAgent.
+ *
+ * The same wallet always produces the same agent identity — no localStorage,
+ * no persistence. Bumping BROWSER_KEY_MESSAGE forks the identity space.
+ *
+ * Privacy invariants:
+ *   - No console.* anywhere.
+ *   - The signature bytes never appear in error messages or stack frames.
+ *   - The derived master seed is passed to createShroudAgent and immediately
+ *     consumed by createAgentIdentity; no caller-visible reference is retained.
+ */
+
+import type { Address } from 'viem';
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+import type { FinalityLevel } from '@shroud-fi/scanning';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import { createShroudAgent } from './factory.js';
+import type { ShroudAgent } from './agent.js';
+import {
+  BROWSER_KEY_MESSAGE,
+  BROWSER_MASTER_SEED_LENGTH,
+  HKDF_BROWSER_INFO,
+  HKDF_BROWSER_SALT,
+} from './constants.js';
+import {
+  BrowserWalletSignatureRejectedError,
+  MissingBrowserWalletError,
+} from './errors.js';
+import type { BrowserWalletAdapter } from './types.js';
+
+export {
+  BROWSER_KEY_MESSAGE,
+  HKDF_BROWSER_SALT,
+  HKDF_BROWSER_INFO,
+} from './constants.js';
+
+export interface CreateShroudAgentFromBrowserWalletArgs {
+  readonly wallet: BrowserWalletAdapter;
+  readonly transport: ShroudFiTransport;
+  readonly stealthContract?: Address;
+  readonly startBlock: bigint;
+  readonly finality?: FinalityLevel;
+}
+
+/**
+ * Decode a 0x-prefixed hex string (e.g. an EIP-191 signature) into bytes.
+ * Returns null on malformed input — callers map this to a privacy-safe error
+ * rather than surfacing the raw value.
+ */
+function hexToBytesSafe(hex: string): Uint8Array | null {
+  if (typeof hex !== 'string') return null;
+  const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (stripped.length === 0 || stripped.length % 2 !== 0) return null;
+  const out = new Uint8Array(stripped.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return null;
+    out[i] = byte;
+  }
+  return out;
+}
+
+/**
+ * Build a ShroudAgent from a browser wallet adapter (e.g. MetaMask).
+ *
+ * @throws MissingBrowserWalletError if the adapter is missing required fields.
+ * @throws BrowserWalletSignatureRejectedError if the signature request is rejected.
+ */
+export async function createShroudAgentFromBrowserWallet(
+  args: CreateShroudAgentFromBrowserWalletArgs,
+): Promise<ShroudAgent> {
+  const wallet = args.wallet;
+  if (
+    wallet === undefined ||
+    wallet === null ||
+    typeof wallet.signMessage !== 'function' ||
+    typeof wallet.address !== 'string' ||
+    !wallet.address.startsWith('0x')
+  ) {
+    throw new MissingBrowserWalletError();
+  }
+
+  let signature: string;
+  try {
+    signature = await wallet.signMessage(BROWSER_KEY_MESSAGE);
+  } catch {
+    // Never surface the underlying rejection reason — could embed wallet
+    // metadata or user prompt text.
+    throw new BrowserWalletSignatureRejectedError();
+  }
+
+  const sigBytes = hexToBytesSafe(signature);
+  if (sigBytes === null || sigBytes.length === 0) {
+    throw new BrowserWalletSignatureRejectedError();
+  }
+
+  // HKDF-SHA256: extract + expand the signature into a deterministic 32-byte
+  // master seed. The signature is the IKM, not the salt — salt and info are
+  // constant version tags.
+  const masterSeed = hkdf(
+    sha256,
+    sigBytes,
+    HKDF_BROWSER_SALT,
+    HKDF_BROWSER_INFO,
+    BROWSER_MASTER_SEED_LENGTH,
+  );
+
+  const config = {
+    masterSeed,
+    transport: args.transport,
+    startBlock: args.startBlock,
+    ...(args.stealthContract !== undefined
+      ? { stealthContract: args.stealthContract }
+      : {}),
+    ...(args.finality !== undefined ? { finality: args.finality } : {}),
+  };
+
+  return createShroudAgent(config);
+}

package/src/constants.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent runtime constants.
+ *
+ * BROWSER_KEY_MESSAGE is the personal-sign payload the browser factory asks
+ * MetaMask (or any EIP-1193 wallet) to sign. It is HKDF'd into a deterministic
+ * 32-byte master seed so the same wallet always produces the same agent
+ * identity — no localStorage, no key persistence.
+ *
+ * Versioning the message string is load-bearing: bumping `-v1` to `-v2` will
+ * derive a different identity even for the same wallet. Treat as a one-way
+ * cryptographic input; never rename without a migration story.
+ */
+
+export const BROWSER_KEY_MESSAGE =
+  'ShroudFi-Demo-Key-Derivation-v1';
+
+export const HKDF_BROWSER_SALT = new TextEncoder().encode('ShroudFi-Demo-v1');
+export const HKDF_BROWSER_INFO = new TextEncoder().encode('agent-master-seed');
+
+export const BROWSER_MASTER_SEED_LENGTH = 32;

package/src/contacts.ts

@@ -0,0 +1,174 @@
+// Address-book / contact registry for @shroud-fi/agent-runtime.
+//
+// Pure-local, file-backed map of human-friendly labels → either a wallet
+// address (0x…) or a stealth meta-address (st:base:…). Persisted at
+// ~/.shroudfi/contacts.json on POSIX, %USERPROFILE%\.shroudfi\contacts.json
+// on Windows. File mode is 0600 on platforms that honour it.
+//
+// Privacy rule: NO method on ContactBook puts the label or the value into an
+// error message. Test file contacts.test.ts asserts this for every error
+// class. Callers who want to surface the label to a UI must read it from the
+// structured Contact object the API returns.
+
+// Bare imports (not `node:` URL scheme) so browser bundlers like webpack can
+// stub these to false via resolve.fallback when ContactBook isn't actually
+// instantiated client-side. See apps/demo/next.config.mjs for the stub.
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+import {
+  ContactAlreadyExistsError,
+  InvalidContactLabelError,
+  InvalidContactValueError,
+  UnknownContactError,
+} from './errors.js';
+import type { Contact, ContactKind } from './types.js';
+
+const SCHEMA_VERSION = 1;
+
+const WALLET_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const META_ADDRESS_RE = /^st:base:0x[0-9a-fA-F]{66,200}$/;
+const LABEL_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+export interface ContactBookOptions {
+  /** Override the on-disk JSON file location. Defaults to the home-dir path. */
+  filePath?: string;
+}
+
+interface FileShape {
+  version?: number;
+  contacts: Record<string, Omit<Contact, 'label'>>;
+}
+
+/**
+ * Local contact registry. Each instance is bound to one JSON file and
+ * re-loads on every read so multiple instances pointed at the same file stay
+ * coherent within a single process.
+ */
+export class ContactBook {
+  private readonly filePath: string;
+
+  constructor(opts: ContactBookOptions = {}) {
+    this.filePath = opts.filePath ?? ContactBook.defaultFilePath();
+    // Touch-load on construction so schema-mismatch errors surface eagerly.
+    this.read();
+  }
+
+  static defaultFilePath(): string {
+    return path.join(os.homedir(), '.shroudfi', 'contacts.json');
+  }
+
+  add(label: string, value: string): Contact {
+    if (!isValidLabel(label)) {
+      throw new InvalidContactLabelError();
+    }
+    const kind = detectKind(value);
+    if (kind === undefined) {
+      throw new InvalidContactValueError();
+    }
+    const file = this.read();
+    if (file.contacts[label] !== undefined) {
+      throw new ContactAlreadyExistsError();
+    }
+    const entry: Omit<Contact, 'label'> = {
+      kind,
+      value,
+      addedAt: new Date().toISOString(),
+    };
+    file.contacts[label] = entry;
+    this.write(file);
+    return { label, ...entry };
+  }
+
+  get(label: string): Contact | undefined {
+    if (!isValidLabel(label)) {
+      // We don't throw — get is read-side, returning undefined matches
+      // typical Map.get ergonomics. Invalid labels can't be in the book.
+      return undefined;
+    }
+    const file = this.read();
+    const entry = file.contacts[label];
+    if (entry === undefined) return undefined;
+    return { label, ...entry };
+  }
+
+  list(): Contact[] {
+    const file = this.read();
+    return Object.entries(file.contacts)
+      .map(([label, entry]) => ({ label, ...entry }))
+      .sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+  }
+
+  remove(label: string): void {
+    const file = this.read();
+    if (file.contacts[label] === undefined) {
+      throw new UnknownContactError();
+    }
+    delete file.contacts[label];
+    this.write(file);
+  }
+
+  // ---------------------------------------------------------------------
+  // internals
+  // ---------------------------------------------------------------------
+
+  private read(): FileShape {
+    if (!fs.existsSync(this.filePath)) {
+      return { version: SCHEMA_VERSION, contacts: {} };
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
+    } catch {
+      // A corrupt file is treated as a fatal-but-privacy-safe error. We do not
+      // leak the file's contents into the error message.
+      throw new InvalidContactValueError();
+    }
+    if (!isFileShape(raw)) {
+      throw new InvalidContactValueError();
+    }
+    const version = raw.version ?? SCHEMA_VERSION;
+    if (version !== SCHEMA_VERSION) {
+      throw new InvalidContactValueError();
+    }
+    return { version, contacts: raw.contacts };
+  }
+
+  private write(file: FileShape): void {
+    const dir = path.dirname(this.filePath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const out: FileShape = { version: SCHEMA_VERSION, contacts: file.contacts };
+    fs.writeFileSync(this.filePath, JSON.stringify(out, null, 2) + '\n', {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+  }
+}
+
+function isValidLabel(label: unknown): label is string {
+  if (typeof label !== 'string') return false;
+  if (!LABEL_RE.test(label)) return false;
+  // Reject anything that looks like an on-chain identifier — eliminates the
+  // foot-gun where a half-typed address gets accepted as a label.
+  if (label.startsWith('0x')) return false;
+  if (label.startsWith('st:')) return false;
+  return true;
+}
+
+function detectKind(value: string): ContactKind | undefined {
+  if (typeof value !== 'string') return undefined;
+  if (WALLET_ADDRESS_RE.test(value)) return 'wallet';
+  if (META_ADDRESS_RE.test(value)) return 'meta';
+  return undefined;
+}
+
+function isFileShape(raw: unknown): raw is FileShape {
+  if (typeof raw !== 'object' || raw === null) return false;
+  const r = raw as Record<string, unknown>;
+  if (r.contacts === undefined || typeof r.contacts !== 'object' || r.contacts === null) {
+    return false;
+  }
+  if (r.version !== undefined && typeof r.version !== 'number') return false;
+  return true;
+}

package/src/errors.ts

@@ -0,0 +1,205 @@
+/**
+ * Privacy-safe error classes for @shroud-fi/agent-runtime.
+ *
+ * Invariants (mirrored from @shroud-fi/scanning + @shroud-fi/payments):
+ *   - No 32-byte hex (key material) in any message.
+ *   - No ephemeral pubkey bytes in any message.
+ *   - No raw signature bytes in any message.
+ *   - No transfer amounts in any message.
+ *   - Messages carry short, structured reasons only.
+ */
+
+export class AgentRuntimeError extends Error {
+  override readonly name: string = 'AgentRuntimeError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class AgentNotStartedError extends AgentRuntimeError {
+  override readonly name: string = 'AgentNotStartedError';
+  constructor() {
+    super('Agent has not been started — call start() first');
+  }
+}
+
+export class AgentAlreadyStartedError extends AgentRuntimeError {
+  override readonly name: string = 'AgentAlreadyStartedError';
+  constructor() {
+    super('Agent already started — call stop() before start() again');
+  }
+}
+
+export class MissingBrowserWalletError extends AgentRuntimeError {
+  override readonly name: string = 'MissingBrowserWalletError';
+  constructor() {
+    super('Browser wallet adapter missing required signMessage or address');
+  }
+}
+
+export class BrowserWalletSignatureRejectedError extends AgentRuntimeError {
+  override readonly name: string = 'BrowserWalletSignatureRejectedError';
+  constructor() {
+    super('Browser wallet rejected signature request');
+  }
+}
+
+/**
+ * Thrown when `sweepViaRelayer` is called but no relayer contract has been
+ * registered for the agent's chain. Callers can pass an explicit
+ * `relayerContract` to override the lookup.
+ */
+export class RelayerContractNotConfiguredError extends AgentRuntimeError {
+  override readonly name: string = 'RelayerContractNotConfiguredError';
+  constructor() {
+    super('Relayer contract not configured for this chain');
+  }
+}
+
+/**
+ * P5.1 — thrown when the caller tries to use the ETH gasless sweep path but
+ * has not provided a `selfHostEndpoint`. ETH gasless requires a self-host
+ * relayer service that builds + broadcasts the EIP-7702 type-0x04 tx; there
+ * is no third-party fallback (Gelato's 7702 surface is wallet-shaped, not
+ * relayer-shaped).
+ */
+export class EthRelayerEndpointRequiredError extends AgentRuntimeError {
+  override readonly name: string = 'EthRelayerEndpointRequiredError';
+  constructor() {
+    super(
+      'ETH gasless sweep requires a self-host relayer endpoint — pass relayerOptions.selfHostEndpoint',
+    );
+  }
+}
+
+/**
+ * P5.1 — thrown when no ShroudFiEthRelayer contract has been registered for
+ * the agent's chain and the caller did not pass `ethRelayerContract` to
+ * override the manifest lookup.
+ */
+export class EthRelayerContractNotConfiguredError extends AgentRuntimeError {
+  override readonly name: string = 'EthRelayerContractNotConfiguredError';
+  constructor() {
+    super('ShroudFiEthRelayer contract not configured for this chain');
+  }
+}
+
+/**
+ * @deprecated Retained as a soft-removed export — callers updated to use
+ * EthRelayerEndpointRequiredError or the gasless ETH path directly. P5.1
+ * activated the previously-stubbed ETH-via-relayer path.
+ */
+export class RelayerNotAvailableForETHError extends AgentRuntimeError {
+  override readonly name: string = 'RelayerNotAvailableForETHError';
+  constructor() {
+    super('Relayer sweep does not support ETH — use direct sweep or ERC-20');
+  }
+}
+
+/**
+ * M3 — thrown when `register()` is called but the agent's registrant wallet
+ * already has a non-empty stealth meta-address on file in the canonical
+ * ERC-6538 registry for scheme 1. Callers should treat this as benign and
+ * skip the registration tx; `ensureRegistered` does this automatically.
+ *
+ * Privacy: the registrant wallet address is NOT placed in `.message` — it
+ * would link the agent's runtime wallet to the error log. Callers who need
+ * to display the wallet must source it from `transport.walletClient.account`
+ * themselves.
+ */
+export class AlreadyRegisteredError extends AgentRuntimeError {
+  override readonly name: string = 'AlreadyRegisteredError';
+  constructor() {
+    super('Agent is already registered in the ERC-6538 registry');
+  }
+}
+
+/**
+ * M3 — wraps an underlying error thrown while `ensureRegistered` runs inside
+ * `agent.sendToWallet` with `autoRegister: true`. Preserves the original via
+ * the standard `cause` chain so callers can introspect without parsing
+ * strings.
+ *
+ * Privacy: the inner error MUST itself comply with the runtime's no-amount /
+ * no-wallet / no-key rule. This wrapper never inlines key, signature, or
+ * amount material into its own message.
+ */
+export class AutoRegistrationFailedError extends AgentRuntimeError {
+  override readonly name: string = 'AutoRegistrationFailedError';
+  constructor(cause?: unknown) {
+    super('Auto-registration failed');
+    // Use the standard ES2022 `cause` slot. Avoid serializing the inner
+    // error into the message itself — the privacy invariant tests would
+    // catch a leak if the wrapped error embedded sensitive bytes.
+    if (cause !== undefined) {
+      (this as { cause?: unknown }).cause = cause;
+    }
+  }
+}
+
+/**
+ * M3 — thrown when `register()` is invoked on a transport that has no
+ * `walletClient` (or no account on the walletClient). Registration is a state
+ * change tx that needs a signer; read-only transports cannot register.
+ */
+export class RegistrationRequiresWalletError extends AgentRuntimeError {
+  override readonly name: string = 'RegistrationRequiresWalletError';
+  constructor() {
+    super('Registration requires a walletClient with an account');
+  }
+}
+
+/**
+ * v0.1.1 — ContactBook: thrown when a label fails validation (empty,
+ * whitespace-only, control chars, looks like an address, longer than 64 chars,
+ * or contains characters outside [A-Za-z0-9._-]).
+ *
+ * Privacy: the offending label string is NOT placed in the message — it would
+ * end up in error logs / stack traces. Callers must surface the label from
+ * their own UI state.
+ */
+export class InvalidContactLabelError extends AgentRuntimeError {
+  override readonly name: string = 'InvalidContactLabelError';
+  constructor() {
+    super('Contact label is not valid (must match [A-Za-z0-9._-]{1,64})');
+  }
+}
+
+/**
+ * v0.1.1 — ContactBook: thrown when a value is neither a 20-byte wallet
+ * address nor a stealth meta-address on `base`.
+ *
+ * Privacy: the offending value is NOT placed in the message.
+ */
+export class InvalidContactValueError extends AgentRuntimeError {
+  override readonly name: string = 'InvalidContactValueError';
+  constructor() {
+    super('Contact value must be a wallet address (0x…) or a meta-address (st:base:0x…)');
+  }
+}
+
+/**
+ * v0.1.1 — ContactBook: thrown when add() is called with a label already
+ * present in the book.
+ *
+ * Privacy: the label is NOT placed in the message.
+ */
+export class ContactAlreadyExistsError extends AgentRuntimeError {
+  override readonly name: string = 'ContactAlreadyExistsError';
+  constructor() {
+    super('A contact with that label already exists');
+  }
+}
+
+/**
+ * v0.1.1 — ContactBook: thrown when remove() or a label-resolving send is
+ * called with a label that does not exist in the book.
+ *
+ * Privacy: the label is NOT placed in the message.
+ */
+export class UnknownContactError extends AgentRuntimeError {
+  override readonly name: string = 'UnknownContactError';
+  constructor() {
+    super('No contact with that label');
+  }
+}

package/src/factory.ts

@@ -0,0 +1,51 @@
+/**
+ * createShroudAgent — server / Node entry point.
+ *
+ * Validates configuration, resolves the stealth contract address from the
+ * transport's chain, builds an AgentIdentity from the optional master seed,
+ * and constructs a ShroudAgent.
+ *
+ * Privacy: no seed or key bytes ever appear in error messages. Validation
+ * errors are short structured reasons only.
+ */
+
+import { createAgentIdentity } from '@shroud-fi/core';
+import { getShroudFiStealth } from '@shroud-fi/transport';
+import { ShroudAgent } from './agent.js';
+import type { ShroudAgentInternalOptions } from './agent.js';
+import { AgentRuntimeError } from './errors.js';
+import type { ShroudAgentConfig } from './types.js';
+
+/**
+ * Build a fully-wired ShroudAgent from a config.
+ *
+ * @throws AgentRuntimeError on missing/invalid transport or negative startBlock.
+ */
+export function createShroudAgent(config: ShroudAgentConfig): ShroudAgent {
+  if (config.transport === undefined || config.transport.publicClient === undefined) {
+    throw new AgentRuntimeError('transport.publicClient is required');
+  }
+  if (config.startBlock < 0n) {
+    throw new AgentRuntimeError('startBlock must be non-negative');
+  }
+
+  const chainId = config.transport.chain.id;
+  const stealthContract =
+    config.stealthContract ?? getShroudFiStealth(chainId);
+
+  const identity = createAgentIdentity(config.masterSeed);
+
+  const opts: ShroudAgentInternalOptions = {
+    identity,
+    transport: config.transport,
+    stealthContract,
+    startBlock: config.startBlock,
+    ...(config.finality !== undefined ? { finality: config.finality } : {}),
+    ...(config.announcer !== undefined ? { announcer: config.announcer } : {}),
+    ...(config.autoRegister !== undefined
+      ? { autoRegister: config.autoRegister }
+      : {}),
+  };
+
+  return new ShroudAgent(opts);
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// Public surface — @shroud-fi/agent-runtime
+//
+// Phase 4: ergonomic wrapper around @shroud-fi/core + @shroud-fi/payments +
+// @shroud-fi/scanning + @shroud-fi/transport. Two construction paths:
+//   - createShroudAgent(config) — server / Node / AI agent (deterministic seed)
+//   - createShroudAgentFromBrowserWallet(args) — browser (MetaMask-derived seed)
+//
+// Re-exports trimmed to what callers actually need; deeper helpers stay
+// inside the upstream packages.
+
+// Class + factories
+export { ShroudAgent } from './agent.js';
+export { createShroudAgent } from './factory.js';
+export {
+  createShroudAgentFromBrowserWallet,
+  BROWSER_KEY_MESSAGE,
+  HKDF_BROWSER_SALT,
+  HKDF_BROWSER_INFO,
+} from './browser.js';
+
+// Address book (v0.1.1)
+export { ContactBook } from './contacts.js';
+export type { ContactBookOptions } from './contacts.js';
+
+// Types
+export type {
+  ShroudAgentConfig,
+  ShroudAgentStartOptions,
+  BrowserWalletAdapter,
+  AgentSweepResult,
+  AgentRelayerSweepOptions,
+  AgentRelayerSweepResult,
+  AgentRelayerEthSweepOptions,
+  AgentRelayerEthSweepResult,
+  Contact,
+  ContactKind,
+} from './types.js';
+
+// Errors
+export {
+  AgentRuntimeError,
+  AgentNotStartedError,
+  AgentAlreadyStartedError,
+  MissingBrowserWalletError,
+  BrowserWalletSignatureRejectedError,
+  RelayerNotAvailableForETHError,
+  RelayerContractNotConfiguredError,
+  EthRelayerEndpointRequiredError,
+  EthRelayerContractNotConfiguredError,
+  AlreadyRegisteredError,
+  AutoRegistrationFailedError,
+  RegistrationRequiresWalletError,
+  InvalidContactLabelError,
+  InvalidContactValueError,
+  ContactAlreadyExistsError,
+  UnknownContactError,
+} from './errors.js';