auramaxx 1.0.0-alpha.4

package/server/lib/project-scope.ts

@@ -0,0 +1,239 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { execFileSync } from 'child_process';
+
+export type ProjectScopeCode =
+  | 'PROJECT_SCOPE_MISSING_AURA'
+  | 'PROJECT_SCOPE_INVALID_AURA'
+  | 'PROJECT_SCOPE_DENIED'
+  | 'PROJECT_SCOPE_OVERRIDE_USED';
+
+export interface ScopeCandidate {
+  id?: string;
+  name: string;
+  vaultName: string | null;
+}
+
+export interface ScopeDecision {
+  allowed: boolean;
+  code: ProjectScopeCode | null;
+  remediation: string;
+  normalizedIdentity: { vaultName: string | null; credentialName: string };
+  projectRoot: string | null;
+  auraFingerprint: string | null;
+  allowedCandidates: ScopeCandidate[];
+  overrideUsed?: boolean;
+}
+
+interface ParsedRef {
+  vaultName: string | null;
+  credentialName: string;
+}
+
+function normalize(str: string): string {
+  return str.trim().toLowerCase();
+}
+
+function parseReference(ref: string): ParsedRef {
+  if (ref.startsWith('@')) {
+    const parts = ref.slice(1).split('/');
+    if (parts.length < 3 || !parts[0] || !parts[1]) {
+      throw new Error(`Invalid vault reference: ${ref}`);
+    }
+    return { vaultName: parts[0], credentialName: parts[1] };
+  }
+  const parts = ref.split('/');
+  if (parts.length < 2 || !parts[0]) {
+    throw new Error(`Invalid reference: ${ref}`);
+  }
+  return { vaultName: null, credentialName: parts[0] };
+}
+
+function parseAuraAllowlist(auraPath: string): ParsedRef[] {
+  const content = fs.readFileSync(auraPath, 'utf-8');
+  const refs: ParsedRef[] = [];
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf('=');
+    if (idx === -1) throw new Error(`Invalid line: ${line}`);
+    const ref = line.slice(idx + 1).trim();
+    refs.push(parseReference(ref));
+  }
+
+  return refs;
+}
+
+function findNearestAura(startDir: string): string | null {
+  let current = startDir;
+  while (true) {
+    const candidate = path.join(current, '.aura');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function resolveGitRoot(startDir: string): string | null {
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: startDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return root || null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveAuraPath(opts: { cwd: string; projectRootOverride?: string }): { projectRoot: string | null; auraPath: string | null } {
+  const explicit = opts.projectRootOverride || process.env.AURA_PROJECT_ROOT;
+  if (explicit) {
+    const root = path.resolve(explicit);
+    return { projectRoot: root, auraPath: path.join(root, '.aura') };
+  }
+
+  const gitRoot = resolveGitRoot(opts.cwd);
+  if (gitRoot) {
+    return { projectRoot: gitRoot, auraPath: path.join(gitRoot, '.aura') };
+  }
+
+  const nearestAura = findNearestAura(opts.cwd);
+  if (nearestAura) {
+    return { projectRoot: path.dirname(nearestAura), auraPath: nearestAura };
+  }
+
+  return { projectRoot: null, auraPath: null };
+}
+
+function fingerprint(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+function isAllowed(candidate: ScopeCandidate, refs: ParsedRef[]): boolean {
+  const candName = normalize(candidate.name);
+  const candVault = candidate.vaultName ? normalize(candidate.vaultName) : null;
+  return refs.some((ref) => {
+    if (normalize(ref.credentialName) !== candName) return false;
+    if (!ref.vaultName) return true;
+    return candVault === normalize(ref.vaultName);
+  });
+}
+
+export function evaluateProjectScopeAccess(input: {
+  surface: 'cli_vault_get' | 'cli_env' | 'mcp_get_secret';
+  requested: { vaultName: string | null; credentialName: string };
+  candidates: ScopeCandidate[];
+  actor?: string;
+  cwd?: string;
+  projectRootOverride?: string;
+}): ScopeDecision {
+  const normalizedIdentity = {
+    vaultName: input.requested.vaultName,
+    credentialName: input.requested.credentialName,
+  };
+  const bypass = process.env.AURA_PROJECT_SCOPE_BYPASS === '1';
+
+  if (bypass) {
+    return {
+      allowed: true,
+      code: 'PROJECT_SCOPE_OVERRIDE_USED',
+      remediation: 'Unset AURA_PROJECT_SCOPE_BYPASS to restore strict project scoping.',
+      normalizedIdentity,
+      projectRoot: null,
+      auraFingerprint: null,
+      allowedCandidates: input.candidates,
+      overrideUsed: true,
+    };
+  }
+
+  const cwd = input.cwd || process.cwd();
+  const { projectRoot, auraPath } = resolveAuraPath({ cwd, projectRootOverride: input.projectRootOverride });
+  if (!auraPath || !fs.existsSync(auraPath)) {
+    return {
+      allowed: false,
+      code: 'PROJECT_SCOPE_MISSING_AURA',
+      remediation: 'Add a .aura file in the project root (or set AURA_PROJECT_ROOT / --project-root).',
+      normalizedIdentity,
+      projectRoot,
+      auraFingerprint: null,
+      allowedCandidates: [],
+    };
+  }
+
+  let refs: ParsedRef[];
+  let auraFingerprint: string;
+  try {
+    const content = fs.readFileSync(auraPath, 'utf-8');
+    auraFingerprint = fingerprint(content);
+    refs = parseAuraAllowlist(auraPath);
+  } catch {
+    return {
+      allowed: false,
+      code: 'PROJECT_SCOPE_INVALID_AURA',
+      remediation: 'Fix .aura syntax (ENV=@vault/name/field or ENV=name/field) and retry.',
+      normalizedIdentity,
+      projectRoot,
+      auraFingerprint: null,
+      allowedCandidates: [],
+    };
+  }
+
+  const allowedCandidates = input.candidates.filter((candidate) => isAllowed(candidate, refs));
+  if (allowedCandidates.length === 0) {
+    return {
+      allowed: false,
+      code: 'PROJECT_SCOPE_DENIED',
+      remediation: `Add '${input.requested.credentialName}' to .aura (or use an allowed credential).`,
+      normalizedIdentity,
+      projectRoot,
+      auraFingerprint,
+      allowedCandidates: [],
+    };
+  }
+
+  if (!input.requested.vaultName && allowedCandidates.length > 1) {
+    return {
+      allowed: false,
+      code: 'PROJECT_SCOPE_DENIED',
+      remediation: `Credential '${input.requested.credentialName}' is mapped in multiple vaults. Re-run with explicit --vault.`,
+      normalizedIdentity,
+      projectRoot,
+      auraFingerprint,
+      allowedCandidates: [],
+    };
+  }
+
+  return {
+    allowed: true,
+    code: null,
+    remediation: '',
+    normalizedIdentity,
+    projectRoot,
+    auraFingerprint,
+    allowedCandidates,
+  };
+}
+
+export function emitProjectScopeEvent(input: {
+  actor?: string;
+  surface: 'cli_vault_get' | 'cli_env' | 'mcp_get_secret';
+  requestedCredential: { vaultName: string | null; credentialName: string };
+  decision: ScopeDecision;
+}): void {
+  const event = {
+    actor: input.actor || 'unknown',
+    surface: input.surface,
+    projectRoot: input.decision.projectRoot,
+    auraFingerprint: input.decision.auraFingerprint,
+    requestedCredential: input.requestedCredential,
+    code: input.decision.code,
+    timestamp: new Date().toISOString(),
+    overrideUsed: Boolean(input.decision.overrideUsed),
+  };
+  console.warn(`[project-scope] ${JSON.stringify(event)}`);
+}

package/server/lib/resolve-action.ts

@@ -0,0 +1,427 @@
+/**
+ * Extracted resolve logic from `POST /actions/:id/resolve`.
+ *
+ * Called by both the HTTP route handler and the ApprovalRouter (direct in-process).
+ */
+
+import { prisma } from './db';
+import { events, emitWalletEvent } from './events';
+import { handleAppMessage } from './strategy/engine';
+import { createToken, getTokenHash, escrowToken, type AgentTokenPayload } from './auth';
+import { isValidAgentPubkey, normalizeAgentPubkey } from './credential-transport';
+import { isUnlocked, getColdWalletAddress } from './cold';
+import { normalizeAddress } from './address';
+import { getDefault, getDefaultSync, parseRateLimit } from './defaults';
+import { logger } from './logger';
+import { getErrorMessage } from './error';
+
+export interface ResolveActionOptions {
+  walletAccess?: string[];
+  limits?: Record<string, number>;
+}
+
+export interface ResolveActionResult {
+  success: boolean;
+  statusCode: 200 | 400 | 401 | 404;
+  data: Record<string, unknown>;
+}
+
+/** Track auto-execute callback depth per app to prevent infinite loops */
+const callbackCounts = new Map<string, number[]>();
+
+function canFireCallback(appId: string): boolean {
+  const { max: MAX_CALLBACKS, windowMs: CALLBACK_WINDOW_MS } = parseRateLimit(getDefaultSync('rate.app_callback', '3,120000'));
+  const now = Date.now();
+  const timestamps = callbackCounts.get(appId) || [];
+  const recent = timestamps.filter(t => now - t < CALLBACK_WINDOW_MS);
+  if (recent.length >= MAX_CALLBACKS) return false;
+  recent.push(now);
+  callbackCounts.set(appId, recent);
+  return true;
+}
+
+export async function resolveAction(
+  actionId: string,
+  approved: boolean,
+  opts?: ResolveActionOptions,
+): Promise<ResolveActionResult> {
+  const id = actionId;
+  const walletAccess = opts?.walletAccess;
+  const overrideLimits = opts?.limits;
+
+  if (typeof approved !== 'boolean') {
+    return { success: false, statusCode: 400, data: { success: false, error: 'approved (boolean) is required' } };
+  }
+
+  const request = await prisma.humanAction.findUnique({ where: { id } });
+  if (!request || request.status !== 'pending') {
+    return { success: false, statusCode: 404, data: { success: false, error: 'Action not found or already resolved' } };
+  }
+
+  if (request.type === 'strategy:message') {
+    return { success: false, statusCode: 400, data: { success: false, error: 'Internal message jobs are not manually resolvable' } };
+  }
+
+  // Handle rejection for all types
+  if (!approved) {
+    await prisma.humanAction.update({
+      where: { id },
+      data: { status: 'rejected', resolvedAt: new Date() },
+    });
+
+    events.actionResolved({ id, type: request.type, approved: false, resolvedBy: 'dashboard' });
+    logger.actionResolved(id, request.type, false, 'dashboard');
+
+    // Notify app of rejection via app:emit
+    if (request.type === 'action') {
+      let meta: { agentId?: string } = {};
+      try { meta = JSON.parse(request.metadata || '{}'); } catch {}
+      emitWalletEvent('app:emit', {
+        strategyId: (meta.agentId || '').replace(/^app:/, ''),
+        channel: 'action:resolved',
+        data: { requestId: id, approved: false },
+      });
+    }
+
+    return { success: true, statusCode: 200, data: { success: true, approved: false } };
+  }
+
+  // === APPROVAL ===
+
+  // Strategy approvals
+  if (request.type === 'strategy:approve') {
+    await prisma.humanAction.update({
+      where: { id },
+      data: { status: 'approved', resolvedAt: new Date() },
+    });
+
+    events.actionResolved({ id, type: request.type, approved: true, resolvedBy: 'dashboard' });
+    return { success: true, statusCode: 200, data: { success: true, approved: true } };
+  }
+
+  // Auth / agent_access / action approvals — generate token
+  if (request.type === 'auth' || request.type === 'agent_access' || request.type === 'action') {
+    if (!isUnlocked()) {
+      return { success: false, statusCode: 401, data: { success: false, error: 'Wallet is locked. Unlock first.' } };
+    }
+
+    let metadata: {
+      agentId?: string;
+      limit?: number;
+      permissions?: string[];
+      ttl?: number;
+      secretHash?: string;
+      limits?: { fund?: number; send?: number; swap?: number };
+      walletAccess?: string[];
+      credentialAccess?: AgentTokenPayload['credentialAccess'];
+      pubkey?: string;
+      strategyId?: string;
+      summary?: string;
+      action?: { endpoint?: string; method?: string; body?: Record<string, unknown> };
+    } = {};
+    if (request.metadata) {
+      try { metadata = JSON.parse(request.metadata); } catch { /* ignore */ }
+    }
+
+    const agentId = metadata.agentId || `agent-${id.slice(0, 8)}`;
+    const defaultFundLimit = await getDefault<number>('limits.fund', 0.1);
+    const defaultSendLimit = await getDefault<number>('limits.send', 0.1);
+    const defaultSwapLimit = await getDefault<number>('limits.swap', 0.1);
+    const defaultPermissions = await getDefault<string[]>('permissions.default', ['wallet:create:hot', 'send:hot', 'swap', 'fund', 'action:create']);
+    const defaultTtl = await getDefault<number>('ttl.agent', 3600);
+    const limit = overrideLimits?.fund ?? metadata.limit ?? defaultFundLimit;
+    const permissions = metadata.permissions || defaultPermissions;
+    const ttl = metadata.ttl || defaultTtl;
+    let normalizedPubkey = metadata.pubkey;
+    if (normalizedPubkey) {
+      if (!isValidAgentPubkey(normalizedPubkey)) {
+        return { success: false, statusCode: 400, data: { success: false, error: 'Stored pubkey is invalid for token issuance' } };
+      }
+      normalizedPubkey = normalizeAgentPubkey(normalizedPubkey);
+    }
+    if (!normalizedPubkey) {
+      return { success: false, statusCode: 400, data: { success: false, error: 'pubkey is required when approving token issuance' } };
+    }
+
+    const finalWalletAccess = walletAccess
+      ? walletAccess.map((addr: string) => normalizeAddress(addr))
+      : metadata.walletAccess;
+
+    // Build limits: per-token overrides > request metadata > system defaults
+    const baseLimits = { fund: limit, send: defaultSendLimit, swap: defaultSwapLimit };
+    const finalLimits = overrideLimits
+      ? { ...baseLimits, ...overrideLimits }
+      : metadata.limits
+        ? { ...baseLimits, ...metadata.limits }
+        : baseLimits;
+
+    const token = await createToken(agentId, limit, permissions, ttl, {
+      limits: finalLimits,
+      walletAccess: finalWalletAccess,
+      credentialAccess: metadata.credentialAccess,
+      agentPubkey: normalizedPubkey,
+    });
+
+    // Escrow the raw token in memory — never store it in the DB
+    escrowToken(id, token);
+
+    // Update request status with tokenHash (not raw token) for audit/display
+    await prisma.humanAction.update({
+      where: { id },
+      data: {
+        status: 'approved',
+        resolvedAt: new Date(),
+        metadata: JSON.stringify({
+          ...metadata,
+          tokenHash: getTokenHash(token),
+          limits: finalLimits,
+          walletAccess: finalWalletAccess,
+          pubkey: normalizedPubkey,
+          credentialAccess: metadata.credentialAccess,
+        }),
+      },
+    });
+
+    // Log the approval
+    await prisma.log.create({
+      data: {
+        walletAddress: getColdWalletAddress() || 'system',
+        title: 'Agent Access Approved',
+        description: `Generated token for ${agentId} with ${limit} ETH limit`,
+      },
+    });
+
+    events.tokenCreated({
+      tokenHash: getTokenHash(token),
+      agentId,
+      limit,
+      permissions,
+      expiresAt: Date.now() + ttl * 1000,
+    });
+    events.actionResolved({ id, type: request.type, approved: true, resolvedBy: 'dashboard' });
+    logger.actionResolved(id, request.type, true, 'dashboard');
+
+    // Notify app of approval via app:emit (always, even with auto-execute)
+    if (request.type === 'action') {
+      emitWalletEvent('app:emit', {
+        strategyId: (metadata.agentId || '').replace(/^app:/, ''),
+        channel: 'action:resolved',
+        data: { requestId: id, approved: true },
+      });
+    }
+
+    // Auto-execute pre-computed action if present in metadata
+    const hasAutoExecute = request.type === 'action' && metadata.action;
+    if (hasAutoExecute) {
+      const action = metadata.action as { endpoint?: string; method?: string; body?: Record<string, unknown> };
+      if (action.endpoint && action.method) {
+        try {
+          const actionUrl = `http://127.0.0.1:4242${action.endpoint}`;
+          const actionRes = await fetch(actionUrl, {
+            method: action.method,
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${token}`,
+            },
+            body: action.method === 'POST' && action.body
+              ? JSON.stringify(action.body)
+              : undefined,
+          });
+          const actionResult = await actionRes.text();
+          let parsedResult: unknown;
+          try { parsedResult = JSON.parse(actionResult); } catch { parsedResult = actionResult; }
+
+          emitWalletEvent('app:emit', {
+            strategyId: (metadata.agentId || '').replace(/^app:/, ''),
+            channel: 'action:executed',
+            data: {
+              requestId: id,
+              approved: true,
+              action: { endpoint: action.endpoint, method: action.method },
+              status: actionRes.ok ? 'success' : 'error',
+              statusCode: actionRes.status,
+              result: parsedResult,
+            },
+          });
+
+          logger.actionResolved(id, 'action:auto-execute', actionRes.ok, 'system');
+
+          // Feed result back to app AI for a contextual follow-up message
+          const appId = (metadata.agentId || '').replace(/^app:/, '');
+          if (appId) {
+            const summary = metadata.summary || 'action';
+            const systemMsg = actionRes.ok
+              ? `[SYSTEM] Action "${summary}" approved and executed successfully.\nResult: ${JSON.stringify(parsedResult).slice(0, 500)}\n\nIf there are more steps needed to complete the user's original request, use your tools NOW (wallet_api or request_human_action) to continue. Do not just describe what you will do — do it.`
+              : `[SYSTEM] Action "${summary}" approved but failed (${actionRes.status}).\nError: ${JSON.stringify(parsedResult).slice(0, 500)}\n\nInvestigate the error using wallet_api and retry with request_human_action if you can fix the issue. Do NOT just explain the error — try to fix it.`;
+
+            if (canFireCallback(appId)) {
+              handleAppMessage(appId, systemMsg).then(({ reply }) => {
+                if (reply) {
+                  emitWalletEvent('app:emit', {
+                    strategyId: appId,
+                    channel: 'agent:message',
+                    data: { message: reply },
+                  });
+                }
+              }).catch((err) => { logger.actionResolved(id, 'action:callback-error', false, getErrorMessage(err)); });
+            } else {
+              logger.actionResolved(id, 'action:callback-limit', true, `app:${appId}`);
+            }
+          }
+        } catch (err) {
+          const errMsg = getErrorMessage(err);
+          emitWalletEvent('app:emit', {
+            strategyId: (metadata.agentId || '').replace(/^app:/, ''),
+            channel: 'action:executed',
+            data: {
+              requestId: id,
+              approved: true,
+              action: { endpoint: action.endpoint, method: action.method },
+              status: 'error',
+              error: errMsg,
+            },
+          });
+
+          // Feed error back to app AI
+          const appId = (metadata.agentId || '').replace(/^app:/, '');
+          if (appId) {
+            const summary = metadata.summary || 'action';
+            const systemMsg = `[SYSTEM] Action "${summary}" approved but execution failed.\nError: ${errMsg}\n\nInvestigate the error using wallet_api and retry with request_human_action if you can fix the issue. Do NOT just explain the error — try to fix it.`;
+
+            if (canFireCallback(appId)) {
+              handleAppMessage(appId, systemMsg).then(({ reply }) => {
+                if (reply) {
+                  emitWalletEvent('app:emit', {
+                    strategyId: appId,
+                    channel: 'agent:message',
+                    data: { message: reply },
+                  });
+                }
+              }).catch((err) => { logger.actionResolved(id, 'action:callback-error', false, getErrorMessage(err)); });
+            } else {
+              logger.actionResolved(id, 'action:callback-limit', false, `app:${appId}`);
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      success: true,
+      statusCode: 200,
+      data: {
+        success: true,
+        token,
+        agentId,
+        limit,
+        limits: finalLimits,
+        permissions,
+        walletAccess: finalWalletAccess,
+        expiresIn: ttl,
+      },
+    };
+  }
+
+  // Permission update approvals — generate token with updated permissions
+  if (request.type === 'permission_update') {
+    if (!isUnlocked()) {
+      return { success: false, statusCode: 401, data: { success: false, error: 'Wallet is locked. Unlock first.' } };
+    }
+
+    let metadata: {
+      agentId?: string;
+      tokenHash?: string;
+      requestedPermissions?: string[];
+      requestedWalletAccess?: string[];
+      requestedLimits?: { fund?: number; send?: number; swap?: number };
+      requestedPubkey?: string;
+      secretHash?: string;
+    } = {};
+    if (request.metadata) {
+      try { metadata = JSON.parse(request.metadata); } catch { /* ignore */ }
+    }
+
+    const agentId = metadata.agentId || `agent-${id.slice(0, 8)}`;
+    const newPermissions = overrideLimits?.permissions ?? metadata.requestedPermissions ?? [];
+    const newWalletAccess = walletAccess
+      ? walletAccess.map((addr: string) => normalizeAddress(addr))
+      : metadata.requestedWalletAccess;
+    const newLimits = overrideLimits || metadata.requestedLimits;
+    let normalizedPubkey = metadata.requestedPubkey;
+    if (normalizedPubkey) {
+      if (!isValidAgentPubkey(normalizedPubkey)) {
+        return { success: false, statusCode: 400, data: { success: false, error: 'requestedPubkey is invalid' } };
+      }
+      normalizedPubkey = normalizeAgentPubkey(normalizedPubkey);
+    }
+    if (!normalizedPubkey) {
+      return { success: false, statusCode: 400, data: { success: false, error: 'requestedPubkey is required for token issuance' } };
+    }
+
+    const ttl = await getDefault<number>('ttl.agent', 3600);
+    const token = await createToken(agentId, newLimits?.fund ?? 0, newPermissions, ttl, {
+      limits: newLimits,
+      walletAccess: newWalletAccess,
+      agentPubkey: normalizedPubkey,
+    });
+
+    // Escrow the raw token in memory — never store it in the DB
+    escrowToken(id, token);
+
+    await prisma.humanAction.update({
+      where: { id },
+      data: {
+        status: 'approved',
+        resolvedAt: new Date(),
+        metadata: JSON.stringify({
+          ...metadata,
+          tokenHash: getTokenHash(token),
+          approvedPermissions: newPermissions,
+          approvedWalletAccess: newWalletAccess,
+          approvedLimits: newLimits,
+          requestedPubkey: normalizedPubkey,
+        }),
+      },
+    });
+
+    await prisma.log.create({
+      data: {
+        walletAddress: getColdWalletAddress() || 'system',
+        title: 'Permission Update Approved',
+        description: `Updated permissions for ${agentId}`,
+      },
+    });
+
+    events.tokenCreated({
+      tokenHash: getTokenHash(token),
+      agentId,
+      limit: newLimits?.fund ?? 0,
+      permissions: newPermissions,
+      expiresAt: Date.now() + ttl * 1000,
+    });
+    events.actionResolved({ id, type: request.type, approved: true, resolvedBy: 'dashboard' });
+
+    return {
+      success: true,
+      statusCode: 200,
+      data: {
+        success: true,
+        token,
+        agentId,
+        permissions: newPermissions,
+        walletAccess: newWalletAccess,
+        limits: newLimits,
+      },
+    };
+  }
+
+  // For other types (fund_transfer, etc.), update DB and emit event
+  await prisma.humanAction.update({
+    where: { id },
+    data: { status: approved ? 'approved' : 'rejected', resolvedAt: new Date() },
+  });
+
+  events.actionResolved({ id, type: request.type, approved, resolvedBy: 'dashboard' });
+
+  return { success: true, statusCode: 200, data: { success: true, approved } };
+}

package/server/lib/resolve.ts

@@ -0,0 +1,36 @@
+import { ethers } from 'ethers';
+import { getRpcUrl } from './config';
+
+/**
+ * Resolve an ENS name (.eth) to an Ethereum address.
+ * Uses ethers built-in provider.resolveName() which handles ENS natively.
+ * ENS resolution always uses Ethereum mainnet (ENS is deployed on L1).
+ */
+export async function resolveName(name: string): Promise<{ address: string; name: string }> {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Name is required');
+  }
+
+  // Only support .eth names for now (.sol is out of scope)
+  if (!name.endsWith('.eth')) {
+    throw new Error(`Unsupported name format: ${name}. Only .eth names are supported.`);
+  }
+
+  // ENS lives on Ethereum mainnet — always resolve against L1
+  const rpcUrl = await getRpcUrl('ethereum');
+  const provider = new ethers.JsonRpcProvider(rpcUrl);
+
+  const address = await provider.resolveName(name);
+  if (!address) {
+    throw new Error(`Could not resolve: ${name}`);
+  }
+
+  return { address, name };
+}
+
+/**
+ * Check if a string looks like an ENS name (contains a dot).
+ */
+export function looksLikeName(value: string): boolean {
+  return value.includes('.') && !value.startsWith('0x') && !value.match(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/);
+}