@ola-893/agentpay-cli 0.1.0 → 0.4.0

package/src/repository-analysis.mjs

@@ -0,0 +1,150 @@
+import { opendir, open, realpath } from 'node:fs/promises';
+import { resolve, relative, extname, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import ts from 'typescript';
+
+const excluded = new Set(['.git', '.local', '.agentpay', '.aws', '.ssh', '.codex', '.agents', 'node_modules', 'target', 'dist', 'build', 'coverage', 'vendor', 'artifacts', 'cache']);
+const extensions = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.rs', '.sol', '.py']);
+const rules = [
+  { id: 'dynamic-eval', severity: 'high', pattern: /\beval\s*\(/, title: 'Dynamic evaluation', recommendation: 'Replace eval with a parser or an explicit operation allowlist; check whether external input reaches this call.' },
+  { id: 'tls-verification-disabled', severity: 'high', pattern: /rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*['"]?0/, title: 'TLS certificate verification disabled', recommendation: 'Enable certificate verification and configure the required CA instead.' },
+  { id: 'shell-execution', severity: 'medium', pattern: /\b(?:exec|execSync)\s*\(/, title: 'Shell execution needs input review', recommendation: 'Prefer execFile with a fixed executable and separate arguments; inspect any user-controlled command interpolation.' },
+  { id: 'raw-html', severity: 'medium', pattern: /dangerouslySetInnerHTML|\.innerHTML\s*=/, title: 'Raw HTML insertion', recommendation: 'Use text rendering or a maintained sanitizer before inserting untrusted content.' },
+  { id: 'fetch-deadline', severity: 'medium', title: 'Fetch deadline needs review', recommendation: 'No explicit AbortSignal is present at this call. Check whether the Request already carries a deadline; otherwise add AbortSignal.timeout or an owner-controlled cancellation signal so a stalled service cannot hold the operation indefinitely.' },
+  { id: 'wildcard-cors', severity: 'medium', pattern: /['"]access-control-allow-origin['"]\s*[:,]\s*['"]\*['"]/i, title: 'Wildcard cross-origin access', recommendation: 'Check whether this endpoint should expose data to every origin; use an origin allowlist when required.' },
+  { id: 'unfinished-work', severity: 'info', pattern: /\b(?:TODO|FIXME)\b/, title: 'Unfinished work marker', recommendation: 'Review this marker and track required work before release.' },
+];
+const hash = text => createHash('sha256').update(text).digest('hex');
+
+function sourceFindings(text, file) {
+  if (!['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'].includes(extname(file))) return [];
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('.tsx') ? ts.ScriptKind.TSX : file.endsWith('.jsx') ? ts.ScriptKind.JSX : file.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+  const shellNames = new Set(), shellNamespaces = new Set(), found = [];
+  const isChildProcess = value => ts.isStringLiteral(value) && ['child_process', 'node:child_process'].includes(value.text);
+  const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : '';
+  function bindings(node) {
+    if (ts.isImportDeclaration(node) && isChildProcess(node.moduleSpecifier)) {
+      const imports = node.importClause;
+      if (imports?.name) shellNamespaces.add(imports.name.text);
+      if (imports?.namedBindings && ts.isNamespaceImport(imports.namedBindings)) shellNamespaces.add(imports.namedBindings.name.text);
+      if (imports?.namedBindings && ts.isNamedImports(imports.namedBindings)) for (const item of imports.namedBindings.elements) if (['exec', 'execSync'].includes((item.propertyName || item.name).text)) shellNames.add(item.name.text);
+    }
+    if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer) && node.initializer.expression.getText(source) === 'require' && node.initializer.arguments[0] && isChildProcess(node.initializer.arguments[0])) {
+      if (ts.isIdentifier(node.name)) shellNamespaces.add(node.name.text);
+      if (ts.isObjectBindingPattern(node.name)) for (const item of node.name.elements) if (['exec', 'execSync'].includes((item.propertyName || item.name).getText(source))) shellNames.add(item.name.getText(source));
+    }
+    ts.forEachChild(node, bindings);
+  }
+  bindings(source);
+  const add = (id, node) => {
+    const rule = rules.find(rule => rule.id === id), line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+    if (!found.some(item => item.rule === id && item.line === line)) found.push({ id: hash(`${file}:${line}:${id}`).slice(0, 16), rule: id, severity: rule.severity, file, line, title: rule.title, recommendation: rule.recommendation });
+  };
+  function visit(node) {
+    if (ts.isCallExpression(node)) {
+      const expression = node.expression;
+      if (ts.isIdentifier(expression) && expression.text === 'eval') add('dynamic-eval', node);
+      if (ts.isIdentifier(expression) && expression.text === 'fetch' && node.arguments.length && !(ts.isNewExpression(node.arguments[0]) && node.arguments[0].expression.getText(source) === 'Request')) {
+        const options = node.arguments[1];
+        if (!options || (ts.isObjectLiteralExpression(options) && !options.properties.some(property => ts.isSpreadAssignment(property) || propertyName(property.name) === 'signal'))) add('fetch-deadline', node);
+      }
+      if ((ts.isIdentifier(expression) && shellNames.has(expression.text)) || (ts.isPropertyAccessExpression(expression) && shellNamespaces.has(expression.expression.getText(source)) && ['exec', 'execSync'].includes(expression.name.text))) add('shell-execution', node);
+      if (ts.isPropertyAccessExpression(expression) && ['setHeader', 'header', 'set'].includes(expression.name.text) && node.arguments.length >= 2 && ts.isStringLiteral(node.arguments[0]) && node.arguments[0].text.toLowerCase() === 'access-control-allow-origin' && ts.isStringLiteral(node.arguments[1]) && node.arguments[1].text === '*') add('wildcard-cors', node);
+    }
+    if (ts.isPropertyAssignment(node)) {
+      const name = propertyName(node.name);
+      if (name === 'rejectUnauthorized' && node.initializer.kind === ts.SyntaxKind.FalseKeyword) add('tls-verification-disabled', node);
+      if (name.toLowerCase() === 'access-control-allow-origin' && ts.isStringLiteral(node.initializer) && node.initializer.text === '*') add('wildcard-cors', node);
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      if (ts.isPropertyAccessExpression(node.left) && node.left.name.text === 'innerHTML') add('raw-html', node);
+      if (node.left.getText(source) === 'process.env.NODE_TLS_REJECT_UNAUTHORIZED' && (ts.isStringLiteral(node.right) && node.right.text === '0')) add('tls-verification-disabled', node);
+    }
+    if (ts.isJsxAttribute(node) && propertyName(node.name) === 'dangerouslySetInnerHTML') add('raw-html', node);
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, text);
+  for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(token) && /\b(?:TODO|FIXME)\b/.test(scanner.getTokenText())) {
+    const line = source.getLineAndCharacterOfPosition(scanner.getTokenPos()).line + 1, rule = rules.find(r => r.id === 'unfinished-work');
+    found.push({ id: hash(`${file}:${line}:${rule.id}`).slice(0, 16), rule: rule.id, severity: rule.severity, file, line, title: rule.title, recommendation: rule.recommendation });
+  }
+  return found.sort((a, b) => a.line - b.line);
+}
+
+// Read only operator-selected regular files. Never execute repository code or follow symlinks.
+export async function analyzeRepository(repository, { maxFiles = 500, maxBytes = 3000000, maxFileBytes = 200000, maxEntries = 10000 } = {}) {
+  const root = await realpath(resolve(repository));
+  const files = [], findings = [], dependencies = [];
+  const languages = {};
+  let bytes = 0, lines = 0, skipped = 0, entriesVisited = 0, limited = false;
+  async function walk(directory) {
+    const entries = [];
+    for await (const entry of await opendir(directory)) {
+      if (++entriesVisited > maxEntries) { limited = true; break; }
+      entries.push(entry);
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.') || excluded.has(entry.name)) continue;
+      const path = resolve(directory, entry.name);
+      const name = relative(root, path).split(sep).join('/');
+      if (entry.isDirectory()) { if (!limited) await walk(path); continue; }
+      if (!entry.isFile() || (!extensions.has(extname(entry.name)) && entry.name !== 'package.json')) continue;
+      if (files.length >= maxFiles || bytes >= maxBytes) { limited = true; continue; }
+      // O_NOFOLLOW closes the symlink-swap window for the final file; verify canonical ancestry too.
+      const canonical = await realpath(path);
+      if (!canonical.startsWith(root + sep)) { skipped++; continue; }
+      const { constants } = await import('node:fs');
+      let handle;
+      try { handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); }
+      catch (error) { if (['ELOOP', 'ENOENT'].includes(error.code)) { skipped++; continue; } throw error; }
+      let text;
+      try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxFileBytes || bytes + info.size > maxBytes) { skipped++; limited ||= bytes + info.size > maxBytes; continue; }
+        const buffer = Buffer.alloc(Math.min(maxFileBytes, maxBytes - bytes) + 1);
+        const read = await handle.read(buffer, 0, buffer.length, 0);
+        if (read.bytesRead > maxFileBytes || bytes + read.bytesRead > maxBytes) { skipped++; limited = true; continue; }
+        text = buffer.subarray(0, read.bytesRead).toString('utf8');
+        bytes += read.bytesRead;
+      } finally { await handle.close(); }
+      if (text.includes('\0')) { skipped++; continue; }
+      const fileLines = text.split(/\r?\n/);
+      files.push({ path: name, lines: fileLines.length, sha256: hash(text) });
+      lines += fileLines.length;
+      const extension = extname(entry.name) || 'json';
+      languages[extension] = (languages[extension] || 0) + 1;
+      if (entry.name === 'package.json') {
+        try {
+          const pkg = JSON.parse(text);
+          for (const [scope, values] of Object.entries({ dependencies: pkg.dependencies, devDependencies: pkg.devDependencies })) {
+            if (!values || typeof values !== 'object' || Array.isArray(values)) continue;
+            // Do not return dependency values: URLs can carry registry credentials.
+            for (const dependency of Object.keys(values)) if (/^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(dependency)) dependencies.push({ manifest: name, name: dependency, scope });
+          }
+        } catch { findings.push({ id: hash(name + ':invalid-manifest').slice(0, 16), rule: 'invalid-manifest', severity: 'medium', file: name, line: 1, title: 'Invalid package manifest', recommendation: 'Correct package.json syntax so dependency tooling can read it.' }); }
+        continue;
+      }
+      findings.push(...sourceFindings(text, name).slice(0, Math.max(0, 300 - findings.length)));
+    }
+  }
+  await walk(root);
+  return { schemaVersion: 1, source: 'AgentPay repository analysis', generatedAt: new Date().toISOString(), fingerprint: hash(JSON.stringify(files)), scope: 'Bounded syntax-based JS/TS heuristics, not a security audit or dataflow analysis. Other source languages contribute inventory only. No source code is executed. Findings need human review; absence of findings does not establish safety.', coverage: { files: files.length, lines, bytes, skipped, limited, maxFiles, maxBytes, maxFileBytes, entriesVisited, maxEntries, maxFindings: 300, findingLimitReached: findings.length === 300 }, languages, files, findings, dependencies };
+}
+
+export function repositoryResponse(snapshot, params) {
+  if ([...params.keys()].some(key => !['view', 'severity', 'file', 'limit', 'offset'].includes(key)) || [...params.keys()].some(key => params.getAll(key).length !== 1)) return { status: 400, body: { error: 'Use view=overview, findings or dependencies; optional severity, exact relative file, limit (1-30) and offset.' } };
+  const limit = Number(params.get('limit') || 5), offset = Number(params.get('offset') || 0);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 30 || !Number.isSafeInteger(offset) || offset < 0 || offset > 10000) return { status: 400, body: { error: 'INVALID_ANALYSIS_PAGINATION' } };
+  const view = params.get('view') || 'overview', severity = params.get('severity'), file = params.get('file');
+  if (!['overview', 'findings', 'dependencies'].includes(view) || (severity && !['high', 'medium', 'info'].includes(severity)) || (file && (file.startsWith('/') || file.includes('\\') || file.split('/').some(part => part === '..' || part.startsWith('.'))))) return { status: 400, body: { error: 'INVALID_ANALYSIS_QUERY' } };
+  const { source, generatedAt, fingerprint, scope, coverage, languages } = snapshot;
+  const body = { source, generatedAt, fingerprint, scope, coverage, view };
+  if (view === 'overview') Object.assign(body, { languages, findingCounts: Object.fromEntries(['high', 'medium', 'info'].map(s => [s, snapshot.findings.filter(f => f.severity === s).length])), dependencyCount: snapshot.dependencies.length });
+  if (view === 'findings') {
+    const matching = snapshot.findings.filter(f => (!severity || f.severity === severity) && (!file || f.file === file));
+    Object.assign(body, { findings: matching.slice(offset, offset + limit), matching: matching.length, offset, limit, truncated: matching.length > offset + limit });
+  }
+  if (view === 'dependencies') Object.assign(body, { dependencies: snapshot.dependencies.slice(0, 80), total: snapshot.dependencies.length, truncated: snapshot.dependencies.length > 80, vulnerabilityDatabaseChecked: false });
+  return { status: 200, body };
+}

package/src/repository-service.mjs

@@ -0,0 +1,17 @@
+import { startProvider } from '@ola-893/agentpay-core/internal-provider';
+import { analyzeRepository, repositoryResponse } from './repository-analysis.mjs';
+
+export async function startRepositoryService(config, { repository, port = 5380, rates, durationSeconds } = {}) {
+  if (!repository) throw new Error('Specify --repository with the operator-selected repository directory.');
+  let cached = await analyzeRepository(repository), refresh;
+  const providerConfig = { ...config };
+  const service = await startProvider(providerConfig, { port, rates, durationSeconds, handleRequest: async params => {
+    if (Date.now() - new Date(cached.generatedAt).getTime() > 5000) {
+      refresh ??= analyzeRepository(repository).then(next => { cached = next; }).finally(() => { refresh = undefined; });
+      await refresh;
+    }
+    return repositoryResponse(cached, params);
+  } });
+  providerConfig.serviceUrl = service.origin;
+  return { ...service, summary: { source: cached.source, fingerprint: cached.fingerprint, coverage: cached.coverage, pricing: { rates: rates || { basic: '10', premium: '200' }, durationSeconds: durationSeconds || 1000, units: 'raw USDC per second; 1000000 raw = 1 USDC', settlement: 'Time-based access, not per-request billing. Accrual continues until closure or lease expiry, including idle time and time before a failure threshold closes the stream.' }, protocol: 'agentpay-near-v1', path: config.service?.requestPath || '/research', views: ['overview', 'findings', 'dependencies'], privateKeysRequired: false } };
+}

package/src/settings.mjs

@@ -0,0 +1,95 @@
+import { resolve, join } from 'node:path';
+import { mkdir, open, unlink } from 'node:fs/promises';
+import { liveProfile } from './config.mjs';
+import { atomicWrite, readOptional } from './files.mjs';
+import { readConfig, readKey } from '@ola-893/agentpay-core/internal-config';
+import { runtimePolicy, serviceConfig } from '@ola-893/agentpay-core/internal-runtime-policy';
+import { inspectNearProfile, NearAgentPayClient } from '@ola-893/agentpay-core/near';
+import { inferenceConfig } from './inference.mjs';
+export { inferenceConfig } from './inference.mjs';
+
+export function usdc(value) {
+  if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,24})(\.[0-9]{1,6})?$/.test(value)) throw new Error('Use a nonnegative USDC amount with at most six decimal places.');
+  const [whole, fraction = ''] = value.split('.');
+  return (BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, '0'))).toString();
+}
+export async function settings(project) {
+  const profile = await liveProfile(project);
+  return { profile, config: await readConfig(profile.configPath) };
+}
+export async function showSettings(project) {
+  const { profile, config } = await settings(project);
+  const { client, summary } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  return { network: config.network, vaultId: config.vaultId, agentId: config.agentId, recipientId: config.recipientId, paymentsEnabled: profile.paymentsEnabled,
+    financialPolicy: (await client.getVault()).policy, financialUnits: 'raw USDC (1 USDC = 1000000)', runtimePolicy: config.runtimePolicy,
+    service: { url: config.serviceUrl, ...config.service }, inference: profile.inference || null, ...summary };
+}
+export async function setRuntime(project, patch) {
+  if (!Object.keys(patch).length) throw new Error('Specify at least one runtime guardrail. See --help.');
+  const { profile, config } = await settings(project);
+  config.runtimePolicy = runtimePolicy({ ...config.runtimePolicy, ...patch });
+  await atomicWrite(profile.configPath, JSON.stringify(config, null, 2));
+  return { runtimePolicy: config.runtimePolicy, enforcement: 'local payment worker; thresholds reload on the next checkpoint', restartRequired: 'Restart running agents/MCP servers after changing reuse, polling or exit behavior.' };
+}
+export async function setService(project, patch) {
+  const { profile, config } = await settings(project);
+  const { summary, client } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  if (summary.activeSession || summary.pendingIntent || summary.executorBusyOrInterrupted) throw new Error('CLOSE_OR_RECONCILE_STREAM_BEFORE_SERVICE_CHANGE');
+  const { url, recipient, ...paths } = patch;
+  const next = { ...config, serviceUrl: url || config.serviceUrl, recipientId: recipient || config.recipientId, service: serviceConfig({ ...config.service, ...paths }) };
+  const temp = profile.configPath + '.candidate.json';
+  await atomicWrite(temp, JSON.stringify(next));
+  let validated;
+  try { validated = await readConfig(temp); } finally { await unlink(temp); }
+  if (!(await client.getVault()).policy.recipients.includes(validated.recipientId)) throw new Error('RECIPIENT_NOT_IN_ONCHAIN_POLICY');
+  await atomicWrite(profile.configPath, JSON.stringify(validated, null, 2));
+  return { service: { url: validated.serviceUrl, recipient: validated.recipientId, ...validated.service }, restartRequired: 'Restart running agents/MCP servers after service changes.' };
+}
+export async function setInference(project, input) {
+  const profile = await liveProfile(project);
+  const inference = inferenceConfig(input);
+  const { file, configPath, stateRoot, ...saved } = profile;
+  await atomicWrite(file, JSON.stringify({ ...saved, inference }, null, 2));
+  return { inference, credentialsStored: false,
+    ...(inference.provider === 'near-ai' ? { attestationVerified: false, policySignerLocation: 'local host' } : {}),
+    next: 'agentpay agent run --prompt "Use the configured paid API to answer my question."' };
+}
+export async function setLimits(project, patch, ownerKeyFile) {
+  if (!ownerKeyFile) throw new Error('--owner-key is required for an on-chain policy change; it is never saved in the agent profile.');
+  if (!Object.keys(patch).length) throw new Error('Specify at least one financial limit.');
+  const { profile, config } = await settings(project);
+  const { client: reader, stateDir } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  const owner = await readKey(resolve(ownerKeyFile));
+  if (owner.accountId !== config.ownerId) throw new Error('OWNER_CREDENTIAL_MISMATCH');
+  const client = new NearAgentPayClient({ vaultId: config.vaultId, accountId: owner.accountId, privateKey: owner.privateKey, rpcUrl: config.rpcUrl });
+  await mkdir(stateDir, { recursive: true, mode: 0o700 });
+  const lock = await open(join(stateDir, 'operation.lock'), 'wx', 0o600);
+  try {
+    if (await readOptional(join(stateDir, 'pending.json'))) throw new Error('RECONCILIATION_REQUIRED');
+    const vault = await reader.getVault();
+    if (vault.active_session) throw new Error('CLOSE_STREAM_BEFORE_POLICY_CHANGE');
+    const policy = { ...vault.policy, ...patch };
+    if (BigInt(policy.budget) < BigInt(vault.spent) || BigInt(policy.max_deposit) <= 0n || BigInt(policy.max_deposit) > BigInt(policy.budget) || BigInt(policy.max_rate) <= 0n || !Number.isInteger(policy.max_duration_seconds) || policy.max_duration_seconds < 1 || policy.max_duration_seconds > 3600 || !policy.recipients.includes(config.recipientId) || policy.recipients.length > 32 || policy.recipients.some(id => !/^[a-z0-9]+(?:[-_.][a-z0-9]+)*$/.test(id) || id.length < 2 || id.length > 64)) throw new Error('INVALID_FINANCIAL_POLICY');
+    const pending = join(stateDir, 'policy-pending.json');
+    const journal = await open(pending, 'wx', 0o600);
+    try { await journal.writeFile(JSON.stringify({ policy, vaultId: config.vaultId, nonceBefore: vault.next_nonce, createdAt: new Date().toISOString() })); await journal.sync(); } finally { await journal.close(); }
+    const receipt = await client.execute('configure', { policy });
+    await atomicWrite(join(stateDir, `policy-${receipt.hash}.receipt.json`), JSON.stringify(receipt));
+    const actual = (await reader.getVault()).policy;
+    if (JSON.stringify(actual) !== JSON.stringify(policy)) throw new Error('POLICY_RECONCILIATION_REQUIRED');
+    await unlink(pending);
+    return { financialPolicy: actual, units: 'raw USDC', transactionHash: receipt.hash, explorerUrl: `https://testnet.nearblocks.io/txns/${receipt.hash}` };
+  } finally { await lock.close(); await unlink(join(stateDir, 'operation.lock')); }
+}
+export async function reconcileLimits(project) {
+  const { profile } = await settings(project);
+  const { client, stateDir } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  const file = join(stateDir, 'policy-pending.json');
+  const text = await readOptional(file);
+  if (!text) return { resolved: true, reason: 'NO_PENDING_POLICY' };
+  const pending = JSON.parse(text), vault = await client.getVault(), actual = vault.policy;
+  if (JSON.stringify(actual) !== JSON.stringify(pending.policy) || pending.nonceBefore === undefined || BigInt(vault.next_nonce) <= BigInt(pending.nonceBefore)) return { resolved: false, reason: 'POLICY_OUTCOME_UNCONFIRMED' };
+  await atomicWrite(file.replace('.json', '.reconciled.json'), JSON.stringify({ ...pending, verifiedAt: new Date().toISOString() }));
+  await unlink(file);
+  return { resolved: true, financialPolicy: actual, receiptRecovered: false };
+}

package/src/setup.mjs

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { mkdir, readFile, stat, open, unlink } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { JsonRpcProvider } from 'near-api-js';
+import { configHome, initProject, liveProfile } from './config.mjs';
+import { atomicWrite, readOptional, safeTarget } from './files.mjs';
+import { readKey, readConfig } from '@ola-893/agentpay-core/internal-config';
+import { NearAgentPayClient } from '@ola-893/agentpay-core/near';
+import { deployTestnet } from '@ola-893/agentpay-core/internal-deployment';
+
+const setupId = project => createHash('sha256').update(project).digest('hex');
+export const bundledWasm = fileURLToPath(new URL('../artifacts/agentpay_vault.wasm', import.meta.url));
+export const publicRecording = fileURLToPath(new URL('../ui/near/testnet.json', import.meta.url));
+
+export async function setupTestnet(project, options) {
+  if (!options.ownerId || !options.ownerKeyFile) return {
+    status: 'OWNER_SETUP_REQUIRED', network: 'testnet', signedTransactions: 0,
+    next: (options.setupCommand ?? 'agentpay init') + ' --network testnet --owner-id YOUR.testnet --owner-key /absolute/path/owner.json',
+    steps: ['Create/export a named NEAR testnet owner account using your wallet or near-cli-rs. Keep its Ed25519 credential JSON private (0600).', 'Fund it with at least 6 test NEAR after storage reserve. The setup creates a vault and restricted agent; recipient defaults to the owner for the local fixture.', 'Run the command above for read-only preflight, then add --deploy to submit setup transactions. No deployment.json or Rust build is required.', 'After setup, use the Circle faucet (Near Testnet) for the printed owner address, then agentpay fund --amount 100000 --owner-key /absolute/path/owner.json.', 'Run Configure the service, inference and financial/runtime guardrails, then enable payments and run agentpay agent run --prompt "...".'],
+    nearAccounts: 'https://docs.near.org/tools/cli', usdcFaucet: 'https://faucet.circle.com/',
+    noSponsor: true,
+  };
+  const { deploymentPlan, inspectTestnet } = await import('@ola-893/agentpay-core/internal-preflight');
+  const key = await readKey(resolve(options.ownerKeyFile));
+  if (key.accountId !== options.ownerId) throw new Error('OWNER_CREDENTIAL_MISMATCH');
+  const plan = deploymentPlan({ ownerId: options.ownerId, recipientId: options.recipientId || options.ownerId, vaultLabel: options.vaultLabel, agentLabel: options.agentLabel, rpcUrl: options.rpcUrl, serviceUrl: options.serviceUrl });
+  const provider = new JsonRpcProvider({ url: plan.rpcUrl });
+  const preflight = await inspectTestnet(plan, { provider, readWasm: () => readFile(bundledWasm), ownerPublicKey: key.publicKey });
+  if (!options.deploy) return { ...preflight, next: preflight.readyToDeploy ? 'Repeat this init command with --deploy. Setup uses up to 6 test NEAR, installs owner-controlled vault/admin keys, and does not fund USDC or enable payments.' : 'Resolve the reported checks, then repeat init. No transaction was signed.' };
+  if (!preflight.readyToDeploy) throw new Error('TESTNET_PREFLIGHT_FAILED: ' + preflight.checks.filter(c => c.status !== 'pass').map(c => `${c.id}: ${c.detail}`).join('; '));
+  const home = configHome();
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  if (((await stat(home)).mode & 0o077) !== 0) throw new Error('AGENTPAY_HOME must have permissions 0700.');
+  const directory = await safeTarget(home, join('setups', setupId(project)));
+  const configPath = join(directory, 'deployment.json');
+  if (await readOptional(await safeTarget(project, '.agentpay/config.json'))) throw new Error('PROJECT_ALREADY_INITIALIZED');
+  const result = await deployTestnet({ ...plan, ownerKeyFile: resolve(options.ownerKeyFile), vaultLabel: options.vaultLabel, agentLabel: options.agentLabel, directory, wasmFile: bundledWasm, onProgress: event => process.stderr.write(`NEAR setup ${event.step}: ${event.transactionHash}\n`) });
+  await initProject(project, { deployment: configPath });
+  return {
+    status: 'DEPLOYED', network: 'testnet', ownerId: result.config.ownerId, vaultId: result.config.vaultId, agentId: result.config.agentId, recipientId: result.config.recipientId,
+    paymentsEnabled: false, ownerUSDCFundingAddress: result.config.ownerId, usdcFaucet: 'https://faucet.circle.com/',
+    transactions: result.record.steps.map(s => ({ step: s.name, hash: s.hash, explorerUrl: `https://testnet.nearblocks.io/txns/${s.hash}` })),
+    privateSetupDirectory: directory, next: 'Get Circle test USDC for the owner (Near Testnet). Then agentpay fund --amount 100000 --owner-key /absolute/path/owner.json. Owner/admin setup credentials are kept separately from the runtime profile.',
+  };
+}
+
+export async function fundProject(project, { ownerKeyFile, amount, decimal = false }) {
+  if (!/^[1-9][0-9]{0,20}$/.test(amount ?? '') || (!decimal && BigInt(amount) > 100000n)) throw new Error(decimal ? 'Provide a positive test USDC amount.' : 'Provide --amount in raw six-decimal USDC units, at most 100000 (0.1 test USDC) per funding call.');
+  if (!ownerKeyFile) throw new Error('--owner-key is required only for this explicit funding operation.');
+  const profile = await liveProfile(project);
+  const config = await readConfig(profile.configPath);
+  const owner = await readKey(resolve(ownerKeyFile));
+  if (owner.accountId !== config.ownerId) throw new Error('OWNER_CREDENTIAL_MISMATCH');
+  const provider = new JsonRpcProvider({ url: config.rpcUrl });
+  if ((await provider.viewNodeStatus()).chain_id !== 'testnet') throw new Error('RPC_NETWORK_MISMATCH');
+  const accessKey = await provider.viewAccessKey({ accountId: config.ownerId, publicKey: owner.publicKey, blockQuery: { finality: 'final' } });
+  if (accessKey.permission !== 'FullAccess') throw new Error('OWNER_FULL_ACCESS_REQUIRED');
+  const client = new NearAgentPayClient({ vaultId: config.vaultId, accountId: owner.accountId, privateKey: owner.privateKey, provider });
+  const vault = await client.getVault();
+  if (vault.owner_id !== owner.accountId || vault.token_id !== config.tokenId) throw new Error('VAULT_IDENTITY_MISMATCH');
+  if (BigInt(await client.tokenBalance(owner.accountId, config.tokenId)) < BigInt(amount)) throw new Error(`OWNER_USDC_INSUFFICIENT: request Near Testnet USDC at https://faucet.circle.com/ for ${owner.accountId}`);
+  const pending = join(configHome(), 'funding', createHash('sha256').update(config.vaultId).digest('hex') + '.json');
+  await mkdir(join(configHome(), 'funding'), { recursive: true, mode: 0o700 });
+  let journal;
+  try { journal = await open(pending, 'wx', 0o600); } catch (e) { if (e.code === 'EEXIST') throw new Error(`FUNDING_RECONCILIATION_REQUIRED: inspect ${pending}. No transaction was resubmitted.`); throw e; }
+  try { await journal.writeFile(JSON.stringify({ network: config.network, vaultId: config.vaultId, ownerId: owner.accountId, amount, createdAt: new Date().toISOString() })); await journal.sync(); } finally { await journal.close(); }
+  const receipt = await client.fund(amount);
+  await atomicWrite(pending.replace('.json', `-${receipt.hash}.receipt.json`), JSON.stringify(receipt));
+  if (receipt.receiptFailures.length || receipt.value !== amount) throw new Error(`FUNDING_NOT_CONFIRMED: ${receipt.hash}; inspect ${pending}.`);
+  await unlink(pending);
+  return { network: 'testnet', amountRawUSDC: amount, transactionHash: receipt.hash, explorerUrl: `https://testnet.nearblocks.io/txns/${receipt.hash}`, next: 'agentpay config show; configure service/inference and guardrails, then agentpay payments --enable and agentpay agent run --prompt "..."' };
+}

package/src/ui.mjs

@@ -3,11 +3,15 @@ import { readFile, realpath } from 'node:fs/promises';
 import { resolve, extname, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import { verifyRun } from '@ola-893/agentpay-core/internal-evidence-audit';
 
 const uiRoot = fileURLToPath(new URL('../ui/', import.meta.url));
 const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.ico': 'image/x-icon' };
-export async function startUi({ port = 0, recording = 'testnet' } = {}) {
+export async function startUi({ port = 0, recording = 'testnet', runFile } = {}) {
   if (!['testnet', 'sandbox'].includes(recording)) throw new Error('Choose --recording testnet or sandbox.');
+  const captured = JSON.parse(await readFile(runFile ? resolve(runFile) : resolve(uiRoot, 'near', `${recording}.json`), 'utf8'));
+  verifyRun(captured);
+  if ((!runFile && captured.network !== recording) || captured.simulated) throw new Error('REPLAY_PROVENANCE_MISMATCH');
   const server = createServer(async (req, res) => {
     const send = (status, body, type = 'text/plain') => {
       res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'x-frame-options': 'DENY', 'referrer-policy': 'no-referrer' });
@@ -19,6 +23,7 @@ export async function startUi({ port = 0, recording = 'testnet' } = {}) {
       const decoded = decodeURIComponent(req.url.split('?')[0]);
       if (decoded.split('/').some(x => x === '..' || x.startsWith('.')) || decoded.includes('\\') || decoded.includes('\0')) return send(403, 'Path denied.');
       if (decoded.startsWith('/api/') || decoded === '/api') return send(404, 'No signing API is exposed by this viewer.');
+      if (runFile && ['/near/latest.json', '/near/testnet.json', '/near/sandbox.json'].includes(decoded)) return send(200, JSON.stringify(captured), 'application/json');
       let path = ['/', '/docs'].includes(decoded) ? '/index.html' : decoded;
       if (path === '/near/latest.json') path = `/near/${recording === 'sandbox' ? 'sandbox' : 'testnet'}.json`;
       const file = await realpath(resolve(uiRoot, `.${path}`));

package/src/vault-money.mjs

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { actions, baseEncode, encodeTransaction, JsonRpcProvider } from 'near-api-js';
+import { atomicWrite, readOptional } from './files.mjs';
+import { fingerprint } from './agents.mjs';
+
+const explorer = hash => `https://testnet.nearblocks.io/txns/${hash}`;
+
+async function finalize(file, intent, outcome) {
+  const tx = outcome.transaction;
+  if (outcome.final_execution_status !== 'FINAL' || tx?.hash !== intent.hash || tx.signer_id !== intent.accountId || tx.receiver_id !== intent.vaultId) throw new Error('VAULT_PAYOUT_OUTCOME_UNCONFIRMED');
+  const status = outcome.status;
+  const ok = status && typeof status === 'object' && 'SuccessValue' in status &&
+    Buffer.from(status.SuccessValue, 'base64').toString() === 'true' &&
+    !outcome.receipts_outcome?.some(receipt => receipt.outcome.status?.Failure);
+  const result = { resolved: true, paid: Boolean(ok), method: intent.method, transactionHash: intent.hash, explorerUrl: explorer(intent.hash) };
+  await atomicWrite(join(file, '..', `receipt-${intent.hash}.json`), JSON.stringify(result));
+  await unlink(file);
+  return result;
+}
+
+export async function payout(agent, client, method, args = {}) {
+  const root = join(agent.path, 'payouts');
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const file = join(root, fingerprint(`${client.vaultId}:${client.accountId}`) + '.pending');
+  const lockFile = file + '.lock';
+  const lock = await open(lockFile, 'wx', 0o600).catch(error => {
+    if (error.code === 'EEXIST') throw new Error('VAULT_PAYOUT_BUSY');
+    throw error;
+  });
+  try {
+    const existing = await readOptional(file);
+    if (existing) throw new Error(`VAULT_PAYOUT_RECONCILIATION_REQUIRED: ${explorer(JSON.parse(existing).hash)}`);
+    const signed = await client.account.createSignedTransaction({ receiverId: client.vaultId, actions: [actions.functionCall(method, args, 100000000000000n)] });
+    const hash = baseEncode(createHash('sha256').update(encodeTransaction(signed.transaction)).digest());
+    const intent = { hash, method, accountId: client.accountId, vaultId: client.vaultId, rpcUrl: client.provider.connection.url };
+    await atomicWrite(file, JSON.stringify(intent));
+    let result;
+    try { result = await finalize(file, intent, await client.provider.sendTransactionUntil(signed, 'FINAL')); }
+    catch { throw new Error(`VAULT_PAYOUT_RECONCILIATION_REQUIRED: ${explorer(hash)}`); }
+    if (!result.paid) throw new Error(`VAULT_PAYOUT_FAILED: ${result.explorerUrl}`);
+    return result;
+  } finally { await lock.close(); await unlink(lockFile); }
+}
+
+export async function reconcilePayouts(agent) {
+  const root = join(agent.path, 'payouts');
+  let files;
+  try { files = await readdir(root); } catch (error) { if (error.code === 'ENOENT') return { resolved: true, transactions: [] }; throw error; }
+  const transactions = [];
+  for (const name of files.filter(item => /^[a-f0-9]{64}\.pending$/.test(item))) {
+    const file = join(root, name), lockFile = file + '.lock';
+    let lock;
+    try { lock = await open(lockFile, 'wx', 0o600); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; transactions.push({ resolved: false, reason: 'VAULT_PAYOUT_BUSY' }); continue; }
+    try {
+      const pending = await readOptional(file);
+      if (!pending) continue;
+      const intent = JSON.parse(pending);
+      const provider = new JsonRpcProvider({ url: intent.rpcUrl });
+      try {
+        const outcome = await provider.viewTransactionStatus({ txHash: intent.hash, accountId: intent.accountId, waitUntil: 'FINAL' });
+        transactions.push(await finalize(file, intent, outcome));
+      } catch { transactions.push({ resolved: false, transactionHash: intent.hash, explorerUrl: explorer(intent.hash) }); }
+    } finally { await lock.close(); await unlink(lockFile); }
+  }
+  return { resolved: transactions.every(x => x.resolved), transactions };
+}