@framers/agentos-ext-wallet 0.2.0

package/src/SpendingPolicyEnforcer.ts

@@ -0,0 +1,169 @@
+// @ts-nocheck
+/**
+ * @fileoverview Pre-transaction guardrail that enforces spending limits,
+ * category budgets, address whitelists/blacklists, and approval thresholds.
+ *
+ * All amounts are in USD. The enforcer tracks running totals via a
+ * simple ledger interface — callers provide the persistence layer.
+ *
+ * @module wunderland/wallet/SpendingPolicyEnforcer
+ */
+
+import type {
+  SpendCategory,
+  SpendCheckResult,
+  SpendingLedgerEntry,
+  SpendingPolicyConfig,
+} from './types.js';
+
+/** Minimal interface for querying the spending ledger (DB-agnostic). */
+export interface ISpendingLedgerStore {
+  /** Sum all spending for the agent in the given period key (e.g. '2026-03-05'). */
+  sumByPeriod(agentId: string, periodKey: string): Promise<number>;
+  /** Sum spending for a specific category in the given period key. */
+  sumByCategoryAndPeriod(agentId: string, category: SpendCategory, periodKey: string): Promise<number>;
+  /** Record a new ledger entry after a successful spend. */
+  insert(entry: SpendingLedgerEntry): Promise<void>;
+}
+
+export class SpendingPolicyEnforcer {
+  constructor(
+    private readonly policy: SpendingPolicyConfig,
+    private readonly ledger: ISpendingLedgerStore,
+  ) {}
+
+  /**
+   * Check whether a proposed spend is allowed under the current policy.
+   */
+  async canSpend(
+    agentId: string,
+    amountUsd: number,
+    category: SpendCategory,
+    recipientAddress?: string,
+  ): Promise<SpendCheckResult> {
+    // 1. Blocked category check
+    if (this.policy.blockedCategories.includes(category)) {
+      return { allowed: false, reason: `Category "${category}" is blocked by spending policy.` };
+    }
+
+    // 2. Address blacklist check
+    if (recipientAddress && this.policy.blockedAddresses?.includes(recipientAddress)) {
+      return { allowed: false, reason: `Recipient address is blocked.` };
+    }
+
+    // 3. Address whitelist check (if whitelist is set, only whitelisted addresses are allowed)
+    if (
+      recipientAddress
+      && this.policy.allowedAddresses
+      && this.policy.allowedAddresses.length > 0
+      && !this.policy.allowedAddresses.includes(recipientAddress)
+    ) {
+      return { allowed: false, reason: `Recipient address is not in the allowed list.` };
+    }
+
+    // 4. Per-transaction limit
+    if (amountUsd > this.policy.perTransactionLimitUsd) {
+      return {
+        allowed: false,
+        reason: `Amount $${amountUsd.toFixed(2)} exceeds per-transaction limit of $${this.policy.perTransactionLimitUsd.toFixed(2)}.`,
+      };
+    }
+
+    const today = getDailyKey();
+    const month = getMonthlyKey();
+
+    // 5. Daily global limit
+    const dailySpent = await this.ledger.sumByPeriod(agentId, today);
+    const remainingDailyUsd = this.policy.dailyLimitUsd - dailySpent;
+    if (amountUsd > remainingDailyUsd) {
+      return {
+        allowed: false,
+        reason: `Daily limit reached. Spent $${dailySpent.toFixed(2)} of $${this.policy.dailyLimitUsd.toFixed(2)} today.`,
+        remainingDailyUsd: Math.max(0, remainingDailyUsd),
+      };
+    }
+
+    // 6. Monthly global limit
+    const monthlySpent = await this.ledger.sumByPeriod(agentId, month);
+    const remainingMonthlyUsd = this.policy.monthlyLimitUsd - monthlySpent;
+    if (amountUsd > remainingMonthlyUsd) {
+      return {
+        allowed: false,
+        reason: `Monthly limit reached. Spent $${monthlySpent.toFixed(2)} of $${this.policy.monthlyLimitUsd.toFixed(2)} this month.`,
+        remainingMonthlyUsd: Math.max(0, remainingMonthlyUsd),
+      };
+    }
+
+    // 7. Per-category budget check
+    const catBudget = this.policy.categoryBudgets.find((b) => b.category === category);
+    if (catBudget) {
+      const catDailySpent = await this.ledger.sumByCategoryAndPeriod(agentId, category, today);
+      if (amountUsd > catBudget.dailyLimitUsd - catDailySpent) {
+        return {
+          allowed: false,
+          reason: `Daily "${category}" budget exceeded. Spent $${catDailySpent.toFixed(2)} of $${catBudget.dailyLimitUsd.toFixed(2)}.`,
+        };
+      }
+      const catMonthlySpent = await this.ledger.sumByCategoryAndPeriod(agentId, category, month);
+      if (amountUsd > catBudget.monthlyLimitUsd - catMonthlySpent) {
+        return {
+          allowed: false,
+          reason: `Monthly "${category}" budget exceeded. Spent $${catMonthlySpent.toFixed(2)} of $${catBudget.monthlyLimitUsd.toFixed(2)}.`,
+        };
+      }
+    }
+
+    // 8. Human approval threshold
+    const requiresApproval = amountUsd > this.policy.requireApprovalAboveUsd;
+
+    return {
+      allowed: true,
+      requiresApproval,
+      remainingDailyUsd: remainingDailyUsd - amountUsd,
+      remainingMonthlyUsd: remainingMonthlyUsd - amountUsd,
+    };
+  }
+
+  /**
+   * Record a completed spend in the ledger (call after successful tx).
+   */
+  async recordSpend(
+    agentId: string,
+    amountUsd: number,
+    category: SpendCategory,
+  ): Promise<void> {
+    const now = Date.now();
+    const dailyKey = getDailyKey();
+    const monthlyKey = getMonthlyKey();
+
+    // Record both daily and monthly entries
+    await this.ledger.insert({
+      id: `spend-${agentId}-${now}`,
+      agentId,
+      category,
+      amountUsd,
+      periodKey: dailyKey,
+      createdAt: now,
+    });
+    await this.ledger.insert({
+      id: `spend-${agentId}-${now}-m`,
+      agentId,
+      category,
+      amountUsd,
+      periodKey: monthlyKey,
+      createdAt: now,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Date key helpers
+// ---------------------------------------------------------------------------
+
+function getDailyKey(): string {
+  return new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+}
+
+function getMonthlyKey(): string {
+  return new Date().toISOString().slice(0, 7); // YYYY-MM
+}

package/src/cards/CardManager.ts

@@ -0,0 +1,274 @@
+// @ts-nocheck
+/**
+ * @fileoverview High-level card lifecycle manager.
+ *
+ * Mirrors AgentWalletManager's pattern: one card per agent, spending policy
+ * enforcement via the shared SpendingPolicyEnforcer, and in-memory/DB store
+ * abstraction via ICardStore.
+ *
+ * @module wallet/cards/CardManager
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import type { SpendingPolicyEnforcer } from '../SpendingPolicyEnforcer.js';
+import type { SpendCategory } from '../types.js';
+import type { MccCategoryMap } from './MccCategoryMap.js';
+import type {
+  AgentCardRecord,
+  CardConfig,
+  CardTransactionRecord,
+  ICardAdapter,
+  ICardStore,
+  LithicTransaction,
+  SpendingSummary,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// CardManager
+// ---------------------------------------------------------------------------
+
+export interface CardManagerOptions {
+  adapter: ICardAdapter;
+  store: ICardStore;
+  policyEnforcer: SpendingPolicyEnforcer;
+  mccMap: MccCategoryMap;
+  config: CardConfig;
+}
+
+export class CardManager {
+  private readonly adapter: ICardAdapter;
+  private readonly store: ICardStore;
+  private readonly policy: SpendingPolicyEnforcer;
+  private readonly mccMap: MccCategoryMap;
+  private readonly config: CardConfig;
+
+  constructor(opts: CardManagerOptions) {
+    this.adapter = opts.adapter;
+    this.store = opts.store;
+    this.policy = opts.policyEnforcer;
+    this.mccMap = opts.mccMap;
+    this.config = opts.config;
+  }
+
+  // -----------------------------------------------------------------------
+  // Card lifecycle
+  // -----------------------------------------------------------------------
+
+  /**
+   * Issue a new virtual card for the agent.
+   * One card per agent — throws if card already exists.
+   */
+  async issueCard(
+    agentId: string,
+    opts?: { memo?: string; spendLimitUsd?: number },
+  ): Promise<AgentCardRecord> {
+    const existing = await this.store.getCard(agentId);
+    if (existing) {
+      throw new Error(`Agent ${agentId} already has a card (last4: ${existing.last4})`);
+    }
+
+    const spendLimit = opts?.spendLimitUsd ?? this.config.defaultSpendLimitUsd;
+
+    const lithicCard = await this.adapter.createCard({
+      type: 'VIRTUAL',
+      memo: opts?.memo || `Agent ${agentId} virtual card`,
+      spend_limit: Math.round(spendLimit * 100), // Lithic uses cents
+      spend_limit_duration: 'MONTHLY',
+      state: 'OPEN',
+    });
+
+    // Set auth rules for blocked categories
+    const blockedMccs = this.getBlockedMccs();
+    if (blockedMccs.length > 0) {
+      await this.adapter.createAuthRule(lithicCard.token, {
+        blocked_mcc: blockedMccs,
+      });
+    }
+
+    const record: AgentCardRecord = {
+      id: uuidv4(),
+      agentId,
+      lithicCardToken: lithicCard.token,
+      last4: lithicCard.last_four,
+      cardType: lithicCard.type,
+      state: lithicCard.state,
+      spendLimitUsd: spendLimit,
+      spendLimitDuration: 'MONTHLY',
+      network: 'VISA',
+      memo: opts?.memo,
+      createdAt: Date.now(),
+    };
+
+    await this.store.saveCard(record);
+    return record;
+  }
+
+  /** Get the agent's card record, or null. */
+  async getCard(agentId: string): Promise<AgentCardRecord | null> {
+    return this.store.getCard(agentId);
+  }
+
+  /**
+   * Get sensitive card details (PAN, CVV, expiry) for online payments.
+   * Enforces spending policy before revealing details.
+   */
+  async getCardDetails(
+    agentId: string,
+    estimatedAmountUsd?: number,
+    category?: SpendCategory,
+  ): Promise<{ last4: string; expMonth: string; expYear: string; cvv: string; pan: string }> {
+    const card = await this.requireCard(agentId);
+
+    // If an estimated amount is provided, check spending policy first
+    if (estimatedAmountUsd !== undefined) {
+      const check = await this.policy.canSpend(agentId, estimatedAmountUsd, category || 'shopping');
+      if (!check.allowed) {
+        throw new CardSpendingBlockedError(check.reason || 'Spending policy violation');
+      }
+    }
+
+    const lithicCard = await this.adapter.getCard(card.lithicCardToken);
+
+    return {
+      last4: lithicCard.last_four,
+      expMonth: lithicCard.exp_month || '',
+      expYear: lithicCard.exp_year || '',
+      cvv: lithicCard.cvv || '',
+      pan: lithicCard.pan || '',
+    };
+  }
+
+  /** Freeze (pause) the agent's card. */
+  async freezeCard(agentId: string): Promise<void> {
+    const card = await this.requireCard(agentId);
+    if (card.state === 'PAUSED') return;
+    if (card.state === 'CLOSED') throw new Error('Cannot freeze a closed card');
+
+    await this.adapter.pauseCard(card.lithicCardToken);
+    await this.store.updateCardState(agentId, 'PAUSED');
+  }
+
+  /** Unfreeze (resume) the agent's card. */
+  async unfreezeCard(agentId: string): Promise<void> {
+    const card = await this.requireCard(agentId);
+    if (card.state === 'OPEN') return;
+    if (card.state === 'CLOSED') throw new Error('Cannot unfreeze a closed card');
+
+    await this.adapter.resumeCard(card.lithicCardToken);
+    await this.store.updateCardState(agentId, 'OPEN');
+  }
+
+  /** Permanently close the agent's card. */
+  async closeCard(agentId: string): Promise<void> {
+    const card = await this.requireCard(agentId);
+    if (card.state === 'CLOSED') return;
+
+    await this.adapter.closeCard(card.lithicCardToken);
+    await this.store.updateCardState(agentId, 'CLOSED');
+  }
+
+  // -----------------------------------------------------------------------
+  // Spending summary
+  // -----------------------------------------------------------------------
+
+  async getSpendingSummary(agentId: string, period: 'day' | 'month' = 'month'): Promise<SpendingSummary> {
+    const card = await this.requireCard(agentId);
+
+    const now = new Date();
+    let since: number;
+    if (period === 'day') {
+      since = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    } else {
+      since = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+    }
+
+    const txs = await this.store.getTransactionsByPeriod(card.id, since);
+    const settled = txs.filter(t => t.status === 'SETTLED' || t.status === 'PENDING');
+
+    const byCategory = new Map<SpendCategory, number>();
+    let totalUsd = 0;
+
+    for (const tx of settled) {
+      totalUsd += tx.amountUsd;
+      byCategory.set(tx.category, (byCategory.get(tx.category) || 0) + tx.amountUsd);
+    }
+
+    return {
+      totalUsd,
+      period,
+      byCategory: [...byCategory.entries()].map(([category, amountUsd]) => ({ category, amountUsd })),
+      transactionCount: settled.length,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // Webhook processing
+  // -----------------------------------------------------------------------
+
+  /**
+   * Process a Lithic transaction webhook event.
+   * Resolves MCC → category and records the spend in the shared ledger.
+   */
+  async processWebhookTransaction(agentId: string, lithicTx: LithicTransaction): Promise<void> {
+    const card = await this.store.getCard(agentId);
+    if (!card) return; // Unknown card — ignore
+
+    const category = this.mccMap.mccToCategory(lithicTx.merchant.mcc);
+    const amountUsd = Math.abs(lithicTx.amount) / 100; // Lithic amounts are in cents
+
+    const txRecord: CardTransactionRecord = {
+      id: uuidv4(),
+      cardId: card.id,
+      lithicTxToken: lithicTx.token,
+      merchantName: lithicTx.merchant.descriptor,
+      merchantMcc: lithicTx.merchant.mcc,
+      category,
+      amountUsd,
+      status: lithicTx.status,
+      createdAt: Date.now(),
+    };
+
+    await this.store.insertTransaction(txRecord);
+
+    // Record in shared spending ledger (same as crypto sends)
+    if (lithicTx.status === 'SETTLED' || lithicTx.status === 'PENDING') {
+      await this.policy.recordSpend(agentId, amountUsd, category);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+
+  private async requireCard(agentId: string): Promise<AgentCardRecord> {
+    const card = await this.store.getCard(agentId);
+    if (!card) {
+      throw new Error(`No card found for agent ${agentId}. Issue one first.`);
+    }
+    return card;
+  }
+
+  /**
+   * Build a flat list of blocked MCC codes from the spending policy's
+   * blockedCategories, expanded via the MCC map.
+   */
+  private getBlockedMccs(): string[] {
+    // Access the policy's config to get blocked categories
+    // The SpendingPolicyEnforcer doesn't expose config directly,
+    // so we pass blocked categories through the card config or
+    // use the MCC map to expand known blocked categories.
+    // For now, this is handled at the extension pack level.
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+export class CardSpendingBlockedError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'CardSpendingBlockedError';
+  }
+}

package/src/cards/LithicCardAdapter.ts

@@ -0,0 +1,159 @@
+// @ts-nocheck
+/**
+ * @fileoverview Pure REST client for the Lithic card issuance API.
+ *
+ * No SDK dependency — uses fetch() directly. Supports sandbox and production
+ * environments via configurable base URL.
+ *
+ * @see https://docs.lithic.com/reference
+ * @module wallet/cards/LithicCardAdapter
+ */
+
+import type {
+  AuthRuleParams,
+  CreateCardParams,
+  ICardAdapter,
+  LithicCardResponse,
+  LithicTransaction,
+  ListTxOpts,
+  UpdateCardParams,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface LithicCardAdapterOptions {
+  apiKey: string;
+  /** Use sandbox environment. Defaults to true. */
+  sandbox?: boolean;
+  /** Override base URL (for testing). */
+  baseUrl?: string;
+}
+
+const SANDBOX_URL = 'https://sandbox.lithic.com/v1';
+const PRODUCTION_URL = 'https://api.lithic.com/v1';
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+export class LithicCardAdapter implements ICardAdapter {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(opts: LithicCardAdapterOptions) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl || (opts.sandbox !== false ? SANDBOX_URL : PRODUCTION_URL);
+  }
+
+  // -----------------------------------------------------------------------
+  // Card CRUD
+  // -----------------------------------------------------------------------
+
+  async createCard(params: CreateCardParams): Promise<LithicCardResponse> {
+    return this.post<LithicCardResponse>('/cards', params);
+  }
+
+  async getCard(cardToken: string): Promise<LithicCardResponse> {
+    return this.get<LithicCardResponse>(`/cards/${cardToken}`);
+  }
+
+  async updateCard(cardToken: string, updates: UpdateCardParams): Promise<LithicCardResponse> {
+    return this.patch<LithicCardResponse>(`/cards/${cardToken}`, updates);
+  }
+
+  async pauseCard(cardToken: string): Promise<void> {
+    await this.patch(`/cards/${cardToken}`, { state: 'PAUSED' });
+  }
+
+  async resumeCard(cardToken: string): Promise<void> {
+    await this.patch(`/cards/${cardToken}`, { state: 'OPEN' });
+  }
+
+  async closeCard(cardToken: string): Promise<void> {
+    await this.patch(`/cards/${cardToken}`, { state: 'CLOSED' });
+  }
+
+  // -----------------------------------------------------------------------
+  // Transactions
+  // -----------------------------------------------------------------------
+
+  async listTransactions(cardToken: string, opts?: ListTxOpts): Promise<LithicTransaction[]> {
+    const params = new URLSearchParams();
+    params.set('card_token', cardToken);
+    if (opts?.begin) params.set('begin', opts.begin);
+    if (opts?.end) params.set('end', opts.end);
+    if (opts?.page_size) params.set('page_size', String(opts.page_size));
+
+    const result = await this.get<{ data: LithicTransaction[] }>(`/transactions?${params.toString()}`);
+    return result.data;
+  }
+
+  // -----------------------------------------------------------------------
+  // Auth rules (MCC-based spending controls)
+  // -----------------------------------------------------------------------
+
+  async createAuthRule(cardToken: string, rule: AuthRuleParams): Promise<void> {
+    await this.post('/auth_rules', {
+      card_tokens: [cardToken],
+      ...rule,
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // HTTP helpers
+  // -----------------------------------------------------------------------
+
+  private async get<T>(path: string): Promise<T> {
+    return this.request<T>('GET', path);
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('POST', path, body);
+  }
+
+  private async patch<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('PATCH', path, body);
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      'Authorization': this.apiKey,
+      'Accept': 'application/json',
+    };
+    if (body) headers['Content-Type'] = 'application/json';
+
+    const resp = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      throw new LithicApiError(resp.status, `Lithic API error ${resp.status}: ${text}`, path);
+    }
+
+    // Some endpoints return no body (204)
+    if (resp.status === 204) return undefined as T;
+
+    return resp.json() as Promise<T>;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class LithicApiError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+    public readonly path: string,
+  ) {
+    super(message);
+    this.name = 'LithicApiError';
+  }
+}