@opencard-dev/core 0.1.0

package/dist/rules-engine.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Rules Engine
+ * ============
+ * Two responsibilities:
+ *
+ *  1. SpendRules — a fluent builder that makes it easy to construct SpendRule
+ *     objects without remembering field names. Also ships pre-built templates
+ *     for common agent configurations.
+ *
+ *  2. evaluateAuthorization — takes a live Stripe authorization request plus
+ *     a card's rules and returns an approve/decline decision. This is called
+ *     from the webhook handler in real time (within the ~2s Stripe window).
+ *
+ * All amounts are in cents throughout. Stripe uses cents; we match that to
+ * avoid any float-to-dollar conversion bugs.
+ *
+ * ─── Design philosophy ───────────────────────────────────────────────────────
+ * The rules engine enforces two core hard controls:
+ *   1. Spend limits (daily, monthly, per-transaction)
+ *   2. Category locks (allowed/blocked merchant categories)
+ *
+ * Confidence scoring — where agents self-report how sure they are about a
+ * purchase — was deliberately removed. Self-reported confidence is unreliable:
+ * an agent with no safety awareness will report 1.0; a cautious agent might
+ * report 0.7 for a perfectly reasonable purchase. It adds noise without
+ * adding real safety. Hard limits are the guardrail. Category locks add
+ * specificity. That's the model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpendRules = void 0;
+exports.evaluateRule = evaluateRule;
+exports.evaluateAuthorization = evaluateAuthorization;
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('rules-engine');
+class SpendRules {
+    rule = {};
+    /**
+     * Create a new SpendRules builder
+     */
+    constructor() {
+        this.rule = {};
+    }
+    /**
+     * Load a pre-built template
+     */
+    static template(template) {
+        const builder = new SpendRules();
+        switch (template) {
+            case 'balanced':
+                // Reasonable defaults for a general-purpose agent card.
+                // Hard daily limit + per-transaction cap, decline on violation.
+                return builder
+                    .dailyLimit(50000) // $500/day
+                    .maxPerTx(10000) // $100/tx
+                    .onFailure('decline')
+                    .name('Balanced')
+                    .description('General-purpose card with a $500/day cap and $100 per-transaction limit');
+            case 'category_locked':
+                // Restricted categories with low per-transaction limit
+                return builder
+                    .category(['grocery', 'transit', 'fuel'])
+                    .maxPerTx(2000) // $20/tx max
+                    .dailyLimit(10000) // $100/day
+                    .onFailure('decline')
+                    .name('Category Locked')
+                    .description('Restricted to specific categories, low transaction limit');
+            case 'daily_limit':
+                // Simple daily budget
+                return builder
+                    .dailyLimit(10000) // $100/day
+                    .onFailure('decline')
+                    .name('Daily Limit')
+                    .description('Hard daily spending cap of $100');
+            case 'approval_gated':
+                // High transactions require human approval.
+                // Note: 'alert' onFailure behaves as 'decline' today (see onFailure docs).
+                // Use the opencard_request_approval MCP tool for actual human-in-the-loop approval.
+                return builder
+                    .approvalThreshold(5000) // $50+
+                    .requiresApproval(true)
+                    .onFailure('decline')
+                    .name('Approval Gated')
+                    .description('Transactions over $50 require human approval');
+            default:
+                const _exhaustive = template;
+                return _exhaustive;
+        }
+    }
+    /**
+     * Set allowed merchant categories
+     * Only transactions in these categories will be approved
+     */
+    category(categories) {
+        this.rule.allowedCategories = categories;
+        return this;
+    }
+    /**
+     * Set blocked merchant categories
+     * Transactions in these categories will be declined
+     */
+    blockCategory(categories) {
+        this.rule.blockedCategories = categories;
+        return this;
+    }
+    /**
+     * Set maximum amount per transaction (in cents)
+     */
+    maxPerTx(cents) {
+        if (cents < 0) {
+            throw new Error('Max per transaction must be >= 0');
+        }
+        this.rule.maxPerTransaction = cents;
+        return this;
+    }
+    /**
+     * Set daily spending limit (in cents)
+     */
+    dailyLimit(cents) {
+        if (cents < 0) {
+            throw new Error('Daily limit must be >= 0');
+        }
+        this.rule.dailyLimit = cents;
+        this.rule.spendingInterval = 'daily';
+        return this;
+    }
+    /**
+     * Set monthly spending limit (in cents)
+     */
+    monthlyLimit(cents) {
+        if (cents < 0) {
+            throw new Error('Monthly limit must be >= 0');
+        }
+        this.rule.monthlyLimit = cents;
+        this.rule.spendingInterval = 'monthly';
+        return this;
+    }
+    /**
+     * Set per-authorization limit (in cents)
+     */
+    perAuthLimit(cents) {
+        if (cents < 0) {
+            throw new Error('Per-auth limit must be >= 0');
+        }
+        this.rule.maxPerTransaction = cents;
+        this.rule.spendingInterval = 'per_authorization';
+        return this;
+    }
+    /**
+     * Set whether transactions above the approval threshold require human sign-off.
+     * Usually you don't call this directly — `approvalThreshold()` sets it automatically.
+     * But you can call it explicitly if you need to toggle approval requirements
+     * independently of the threshold value.
+     */
+    requiresApproval(required) {
+        this.rule.requiresApproval = required;
+        return this;
+    }
+    /**
+     * Set approval threshold (in cents)
+     * Transactions above this amount require human approval.
+     * Also sets requiresApproval = true automatically.
+     */
+    approvalThreshold(cents) {
+        if (cents < 0) {
+            throw new Error('Approval threshold must be >= 0');
+        }
+        this.rule.approvalThreshold = cents;
+        this.rule.requiresApproval = true;
+        return this;
+    }
+    /**
+     * Set failure handling behavior.
+     *
+     * Currently only 'decline' is fully implemented in the authorization flow.
+     * 'alert' and 'pause' are accepted for forward compatibility but behave
+     * the same as 'decline' today — the charge is declined. These modes will
+     * be wired to notification and card-pausing logic in a future release.
+     */
+    onFailure(action) {
+        this.rule.onFailure = action;
+        return this;
+    }
+    /**
+     * Set human-readable name for this rule set
+     */
+    name(name) {
+        this.rule.name = name;
+        return this;
+    }
+    /**
+     * Set human-readable description for this rule set
+     */
+    description(desc) {
+        this.rule.description = desc;
+        return this;
+    }
+    /**
+     * Build and return the final SpendRule object
+     */
+    build() {
+        if (this.rule.onFailure === 'alert' || this.rule.onFailure === 'pause') {
+            logger.warn(`Alert/pause onFailure modes are not yet implemented. Rule will default to decline behavior: ${JSON.stringify(this.rule)}`);
+        }
+        return { ...this.rule };
+    }
+    /**
+     * Get a string representation of the rules
+     */
+    toString() {
+        const parts = [];
+        if (this.rule.allowedCategories?.length) {
+            parts.push(`categories: [${this.rule.allowedCategories.join(', ')}]`);
+        }
+        if (this.rule.maxPerTransaction !== undefined) {
+            const dollars = (this.rule.maxPerTransaction / 100).toFixed(2);
+            parts.push(`max per tx: $${dollars}`);
+        }
+        if (this.rule.dailyLimit !== undefined) {
+            const dollars = (this.rule.dailyLimit / 100).toFixed(2);
+            parts.push(`daily limit: $${dollars}`);
+        }
+        if (this.rule.monthlyLimit !== undefined) {
+            const dollars = (this.rule.monthlyLimit / 100).toFixed(2);
+            parts.push(`monthly limit: $${dollars}`);
+        }
+        if (this.rule.requiresApproval && this.rule.approvalThreshold) {
+            const dollars = (this.rule.approvalThreshold / 100).toFixed(2);
+            parts.push(`approval required >$${dollars}`);
+        }
+        if (this.rule.onFailure) {
+            parts.push(`on violation: ${this.rule.onFailure}`);
+        }
+        return `SpendRules(${parts.join(', ')})`;
+    }
+}
+exports.SpendRules = SpendRules;
+/**
+ * Evaluate a transaction against a rule set
+ * Returns { allowed: boolean, reason?: string }
+ */
+function evaluateRule(rule, transaction) {
+    // Check allowed categories
+    if (rule.allowedCategories?.length &&
+        transaction.category &&
+        !rule.allowedCategories.includes(transaction.category)) {
+        return {
+            allowed: false,
+            reason: `Category '${transaction.category}' not in allowed list`,
+        };
+    }
+    // Check blocked categories
+    if (rule.blockedCategories?.length &&
+        transaction.category &&
+        rule.blockedCategories.includes(transaction.category)) {
+        return {
+            allowed: false,
+            reason: `Category '${transaction.category}' is blocked`,
+        };
+    }
+    // Check max per transaction
+    if (rule.maxPerTransaction !== undefined &&
+        transaction.amount > rule.maxPerTransaction) {
+        const txDollars = (transaction.amount / 100).toFixed(2);
+        const maxDollars = (rule.maxPerTransaction / 100).toFixed(2);
+        return {
+            allowed: false,
+            reason: `Transaction amount $${txDollars} exceeds per-tx limit $${maxDollars}`,
+        };
+    }
+    // If all checks pass
+    return { allowed: true };
+}
+/**
+ * evaluateAuthorization
+ * ──────────────────────
+ * The core decision function. Given a live Stripe authorization request and
+ * the card's spending rules, determines whether to approve or decline.
+ *
+ * Rules are checked in order of cheapest/fastest first:
+ *  1. Merchant category (allowed list, then blocked list)
+ *  2. Per-transaction amount limit
+ *  3. Daily budget (current spend + this tx > limit?)
+ *  4. Monthly budget
+ *
+ * The first failing check short-circuits and returns a decline with a reason
+ * string that explains exactly which rule tripped.
+ *
+ * @param auth    - The Stripe Issuing.Authorization from the webhook event
+ * @param rules   - The SpendRule configured for this card
+ * @param context - Current spend totals from the tracker
+ * @returns AuthorizationDecision with approved flag and human-readable reason
+ */
+function evaluateAuthorization(auth, rules, context) {
+    // ── Extract key fields from the Stripe authorization object ─────────────
+    //
+    // auth.amount — the amount in cents the merchant is requesting
+    // auth.merchant_data.category — MCC (merchant category code) as a string
+    //   e.g. "grocery_stores", "airlines", "restaurants"
+    const amount = auth.amount; // cents
+    const category = auth.merchant_data?.category || '';
+    // ── Check 1: Allowed categories ─────────────────────────────────────────
+    // If the rule specifies an allowlist, the merchant's category MUST be on it.
+    // This is useful for cards meant for a specific purpose (e.g. a card that
+    // should only be used for SaaS subscriptions).
+    if (rules.allowedCategories && rules.allowedCategories.length > 0) {
+        if (category && !rules.allowedCategories.includes(category)) {
+            return {
+                approved: false,
+                reason: `Merchant category '${category}' is not in the allowed list: [${rules.allowedCategories.join(', ')}]`,
+            };
+        }
+    }
+    // ── Check 2: Blocked categories ─────────────────────────────────────────
+    // If the rule specifies a blocklist, ANY match immediately declines.
+    // Blocked list takes precedence even if the category is also in the allowed
+    // list (though that would be a misconfigured rule).
+    if (rules.blockedCategories && rules.blockedCategories.length > 0) {
+        if (category && rules.blockedCategories.includes(category)) {
+            return {
+                approved: false,
+                reason: `Merchant category '${category}' is explicitly blocked`,
+            };
+        }
+    }
+    // ── Check 3: Per-transaction limit ──────────────────────────────────────
+    // The simplest budget check: if this single transaction is too large,
+    // decline it regardless of running totals.
+    if (rules.maxPerTransaction !== undefined && amount > rules.maxPerTransaction) {
+        const txDollars = (amount / 100).toFixed(2);
+        const limitDollars = (rules.maxPerTransaction / 100).toFixed(2);
+        return {
+            approved: false,
+            reason: `Transaction $${txDollars} exceeds per-transaction limit of $${limitDollars}`,
+        };
+    }
+    // ── Check 4: Daily budget ────────────────────────────────────────────────
+    // Would adding this transaction push today's total over the daily limit?
+    // We use the PROSPECTIVE total (spent + this amount) not the current total,
+    // so a card at $95/day with a $100 limit can't approve a $10 transaction.
+    if (rules.dailyLimit !== undefined) {
+        const prospectiveDaily = context.dailySpend + amount;
+        if (prospectiveDaily > rules.dailyLimit) {
+            const spentDollars = (context.dailySpend / 100).toFixed(2);
+            const txDollars = (amount / 100).toFixed(2);
+            const limitDollars = (rules.dailyLimit / 100).toFixed(2);
+            return {
+                approved: false,
+                reason: `Daily limit exceeded: already spent $${spentDollars} + $${txDollars} > daily limit $${limitDollars}`,
+            };
+        }
+    }
+    // ── Check 5: Monthly budget ─────────────────────────────────────────────
+    // Same as daily, but for the calendar month.
+    if (rules.monthlyLimit !== undefined) {
+        const prospectiveMonthly = context.monthlySpend + amount;
+        if (prospectiveMonthly > rules.monthlyLimit) {
+            const spentDollars = (context.monthlySpend / 100).toFixed(2);
+            const txDollars = (amount / 100).toFixed(2);
+            const limitDollars = (rules.monthlyLimit / 100).toFixed(2);
+            return {
+                approved: false,
+                reason: `Monthly limit exceeded: already spent $${spentDollars} + $${txDollars} > monthly limit $${limitDollars}`,
+            };
+        }
+    }
+    // ── All checks passed ────────────────────────────────────────────────────
+    // If we got here, the transaction satisfies every rule. Approve it.
+    const dollars = (amount / 100).toFixed(2);
+    return {
+        approved: true,
+        reason: `All rules passed — approving $${dollars} at ${auth.merchant_data?.name || 'unknown merchant'}`,
+    };
+}
+//# sourceMappingURL=rules-engine.js.map

package/dist/rules-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-engine.js","sourceRoot":"","sources":["../src/rules-engine.ts"],"names":[],"mappings":"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"}

package/dist/rules-store.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Rules Store
+ * ===========
+ * Persistent storage for SpendRule objects, backed by a local JSON file.
+ *
+ * ─── Why not keep rules in Stripe metadata? ─────────────────────────────────
+ * Storing rules in Stripe card metadata (as we did in Phase 1) is a security
+ * problem: anyone with Stripe dashboard access can edit the rules directly,
+ * bypassing any access controls we might add. By moving rules to our own store,
+ * we control who can read or modify them — and Stripe metadata only holds a
+ * reference ID (opencard_rule_id), not the rules themselves.
+ *
+ * ─── Why a JSON file? ────────────────────────────────────────────────────────
+ * Phase 1 is all about getting something working and safe without adding
+ * operational complexity. A JSON file:
+ *  - Survives process restarts (unlike in-memory)
+ *  - Requires no database setup or migration
+ *  - Is easy to inspect, back up, and version-control
+ *  - Is fast enough for Phase 1 workloads (hundreds of rules, not millions)
+ *
+ * Phase 2 will replace this with a proper database when we need multi-instance
+ * support or higher write throughput.
+ *
+ * ─── File format ─────────────────────────────────────────────────────────────
+ * The file is a JSON object: { [ruleId]: SpendRule }
+ * Example:
+ *   {
+ *     "rule_01HX9K2Z3A4B5C6D7E8F9G0H1J": { "dailyLimit": 10000, "onFailure": "decline" },
+ *     "rule_01HX9K2Z3A4B5C6D7E8F9G0H1K": { "monthlyLimit": 50000 }
+ *   }
+ *
+ * ─── ID format ───────────────────────────────────────────────────────────────
+ * IDs use the format `rule_<timestamp_hex><random_hex>` — lexicographically
+ * sortable (newer rules sort after older ones) and globally unique without
+ * a central counter. We implement this without external dependencies using
+ * Node.js's built-in crypto module.
+ *
+ * ─── Thread safety ───────────────────────────────────────────────────────────
+ * We serialize all writes through a simple async queue (each write awaits the
+ * previous one). This isn't needed for single-threaded Node.js, but it makes
+ * the behavior explicit and protects against future async-write bugs.
+ */
+import { SpendRule } from './types';
+export declare class RulesStore {
+    /**
+     * Path to the JSON file where rules are stored.
+     * Configurable via OPENCARD_RULES_PATH env var.
+     * Defaults to ./opencard-rules.json relative to the process working directory.
+     */
+    private readonly filePath;
+    /**
+     * Internal write queue: we chain writes so concurrent callers don't
+     * corrupt the file by reading stale contents and overwriting each other.
+     */
+    private writeQueue;
+    constructor(filePath?: string);
+    /**
+     * Generates a unique, sortable rule ID.
+     *
+     * Format: `rule_<timestamp_ms_hex><random_8_hex_chars>`
+     * Example: `rule_018f1a2b3c4d5e6f7a8b9c0d`
+     *
+     * - The timestamp prefix makes IDs sort chronologically (newest last in
+     *   a lexicographic sort), which is useful when listing rules.
+     * - The random suffix prevents collisions even if two rules are created
+     *   in the same millisecond.
+     * - No external library needed — uses Node.js built-in crypto.
+     */
+    private generateId;
+    /**
+     * Reads the rules file from disk and parses it.
+     *
+     * If the file doesn't exist yet, returns an empty object (not an error) —
+     * the file will be created on the first write.
+     *
+     * If the file exists but contains invalid JSON, throws an error. This
+     * shouldn't happen in normal operation (we always write valid JSON), but
+     * could happen if the file was manually edited.
+     */
+    private readFile;
+    /**
+     * Writes the entire rules object to disk, atomically.
+     *
+     * We write to a temp file first, then rename it into place. This avoids
+     * leaving a half-written file if the process crashes mid-write.
+     *
+     * All writes are serialized through the writeQueue to prevent concurrent
+     * writes from racing each other.
+     */
+    private writeFile;
+    /**
+     * Creates a new rule in the store.
+     *
+     * Validates the rule before writing — throws if validation fails.
+     * This is the right place to reject bad rules so they never make it
+     * into the store and can never affect a live transaction.
+     *
+     * @param rule - The spend rule to store
+     * @returns The generated rule ID (e.g. "rule_018f1a2b3c4d5e6f7a8b9c0d")
+     *
+     * @throws Error if the rule fails validation
+     *
+     * @example
+     * const ruleId = await rulesStore.createRule({
+     *   dailyLimit: 10000,    // $100/day
+     *   onFailure: 'decline',
+     * });
+     * // ruleId → "rule_018f1a2b3c4d5e6f7a8b9c0d"
+     */
+    createRule(rule: SpendRule): Promise<string>;
+    /**
+     * Looks up a rule by its ID.
+     *
+     * Returns null (not an error) if the rule doesn't exist. This is important
+     * in the webhook path: if a card references a rule ID that's been deleted,
+     * the webhook handler should fall back to default-deny, not crash.
+     *
+     * @param ruleId - The rule ID to look up
+     * @returns The SpendRule, or null if not found
+     *
+     * @example
+     * const rule = await rulesStore.getRule('rule_018f1a2b...');
+     * if (rule === null) {
+     *   // rule was deleted or ID is wrong — use default-deny
+     * }
+     */
+    getRule(ruleId: string): Promise<SpendRule | null>;
+    /**
+     * Updates an existing rule.
+     *
+     * Validates the new rule before writing. The update replaces the entire
+     * rule — it's not a partial merge. Pass the full updated rule object.
+     *
+     * @throws Error if the rule doesn't exist (can't update what isn't there)
+     * @throws Error if the new rule fails validation
+     *
+     * @example
+     * await rulesStore.updateRule('rule_018f1a2b...', {
+     *   dailyLimit: 20000,  // raised from $100 to $200
+     *   onFailure: 'decline',
+     * });
+     */
+    updateRule(ruleId: string, rule: SpendRule): Promise<void>;
+    /**
+     * Deletes a rule from the store.
+     *
+     * Note: this does NOT update any cards that reference this rule.
+     * Cards referencing a deleted rule ID will fall back to default-deny
+     * in the webhook handler (by design — it's better to be safe).
+     *
+     * If the rule doesn't exist, this is a no-op (not an error).
+     *
+     * @param ruleId - The rule ID to delete
+     */
+    deleteRule(ruleId: string): Promise<void>;
+    /**
+     * Lists all rules in the store.
+     *
+     * Returns them sorted by ID (which is chronological since IDs are
+     * timestamp-prefixed). Newest rules appear last.
+     *
+     * @returns Array of { id, rule } objects, sorted by creation order
+     *
+     * @example
+     * const rules = await rulesStore.listRules();
+     * for (const { id, rule } of rules) {
+     *   console.log(`${id}: ${rule.name ?? 'unnamed'}`);
+     * }
+     */
+    listRules(): Promise<{
+        id: string;
+        rule: SpendRule;
+    }[]>;
+}
+/**
+ * Module-level singleton instance of RulesStore.
+ *
+ * Export and use this everywhere, just like the `tracker` singleton.
+ * This ensures all parts of the system share the same file path and
+ * write queue — critical for avoiding concurrent write corruption.
+ *
+ * @example
+ * import { rulesStore } from '@opencard-dev/core';
+ * const ruleId = await rulesStore.createRule({ dailyLimit: 10000 });
+ */
+export declare const rulesStore: RulesStore;
+//# sourceMappingURL=rules-store.d.ts.map

package/dist/rules-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-store.d.ts","sourceRoot":"","sources":["../src/rules-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAcpC,qBAAa,UAAU;IACrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAoC;gBAE1C,QAAQ,CAAC,EAAE,MAAM;IAU7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;;;OASG;YACW,QAAQ;IAgBtB;;;;;;;;OAQG;YACW,SAAS;IA+BvB;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BlD;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAKxD;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBhE;;;;;;;;;;OAUG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C;;;;;;;;;;;;;OAaG;IACG,SAAS,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,EAAE,CAAC;CAO9D;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,YAAmB,CAAC"}