stable-ci 0.1.0

package/dist/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createDemoAdapter } from './adapters/demo.js';
+import { createHttpDemoAdapter } from './adapters/http-demo.js';
+import { createConfiguredHttpAdapter } from './adapters/configured-http.js';
+import { startDemoPaymentApp } from './core/demo-payment-app.js';
+import { loadConfig } from './config.js';
+import { runSuite } from './core/runner.js';
+import { writeJUnit } from './reporters/junit.js';
+import { scenarios } from './scenarios/builtins.js';
+const program = new Command();
+function printResults(adapterName, results) {
+    console.log('Stablecoin Reliability CI');
+    console.log('=========================');
+    console.log('Adapter: ' + adapterName);
+    console.log('');
+    for (const result of results) {
+        console.log((result.passed ? 'PASS' : 'FAIL') +
+            '  ' +
+            result.scenario.name);
+        for (const invariant of result.invariants.filter((x) => !x.passed)) {
+            console.log('      ' + invariant.name);
+            if (invariant.message) {
+                console.log('      ' + invariant.message);
+            }
+        }
+    }
+    const passed = results.filter((result) => result.passed).length;
+    const failed = results.length - passed;
+    console.log('');
+    console.log(passed + ' passed, ' + failed + ' failed');
+}
+program
+    .name('stable-ci')
+    .description('Reliability CI for stablecoin payment integrations')
+    .version('0.1.0');
+program
+    .command('scenarios')
+    .description('List built-in reliability scenarios')
+    .action(() => {
+    console.log('Built-in scenarios:');
+    for (const scenario of scenarios) {
+        console.log('  ' + scenario.name);
+        console.log('    ' + scenario.description);
+        console.log('    Risk: ' + scenario.risk);
+    }
+});
+program
+    .command('test')
+    .description('Run the in-memory reliability test suite')
+    .option('--profile <profile>', 'Demo profile: safe or unsafe', 'safe')
+    .option('--json', 'Output JSON')
+    .action(async (options) => {
+    if (options.profile !== 'safe' && options.profile !== 'unsafe') {
+        console.error('Profile must be safe or unsafe.');
+        process.exitCode = 2;
+        return;
+    }
+    const adapter = createDemoAdapter(options.profile);
+    const results = await runSuite(adapter);
+    if (options.json) {
+        console.log(JSON.stringify({
+            adapter: adapter.name,
+            results,
+        }, null, 2));
+    }
+    else {
+        printResults(adapter.name, results);
+    }
+    if (results.some((result) => !result.passed)) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command('test-http')
+    .description('Run reliability scenarios using real local HTTP fault injection')
+    .option('--profile <profile>', 'HTTP demo profile: safe or unsafe', 'safe')
+    .option('--json', 'Output JSON')
+    .action(async (options) => {
+    if (options.profile !== 'safe' && options.profile !== 'unsafe') {
+        console.error('Profile must be safe or unsafe.');
+        process.exitCode = 2;
+        return;
+    }
+    const adapter = createHttpDemoAdapter(options.profile);
+    const results = await runSuite(adapter);
+    if (options.json) {
+        console.log(JSON.stringify({
+            adapter: adapter.name,
+            results,
+        }, null, 2));
+    }
+    else {
+        printResults(adapter.name, results);
+    }
+    if (results.some((result) => !result.passed)) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command('demo-server')
+    .description('Run the local demo payment application')
+    .option('--profile <profile>', 'Demo profile: safe or unsafe', 'safe')
+    .option('--port <port>', 'Port', '4310')
+    .action(async (options) => {
+    if (options.profile !== 'safe' && options.profile !== 'unsafe') {
+        console.error('Profile must be safe or unsafe.');
+        process.exitCode = 2;
+        return;
+    }
+    const port = Number(options.port);
+    if (!Number.isInteger(port) || port <= 0) {
+        console.error('Port must be a positive integer.');
+        process.exitCode = 2;
+        return;
+    }
+    const app = await startDemoPaymentApp(options.profile, port);
+    console.log('Demo payment app running at ' + app.baseUrl);
+    console.log('Profile: ' + options.profile);
+    console.log('Press Ctrl+C to stop.');
+    await new Promise((resolve) => {
+        let closing = false;
+        const shutdown = async () => {
+            if (closing) {
+                return;
+            }
+            closing = true;
+            await app.close();
+            resolve();
+        };
+        process.once('SIGINT', () => {
+            void shutdown();
+        });
+        process.once('SIGTERM', () => {
+            void shutdown();
+        });
+    });
+});
+program
+    .command('run')
+    .description('Run stable-ci against a configured payment application')
+    .option('-c, --config <path>', 'Path to stable-ci config', 'stable-ci.yml')
+    .option('--json', 'Output JSON')
+    .option('--junit <path>', 'Write JUnit XML report')
+    .action(async (options) => {
+    try {
+        const config = loadConfig(options.config);
+        const adapter = createConfiguredHttpAdapter(config);
+        const selectedScenarios = scenarios
+            .filter((scenario) => config.scenarios.includes(scenario.name))
+            .map((scenario) => ({
+            ...scenario,
+            expected: {
+                ...scenario.expected,
+                ...(config.expectations?.[scenario.name] ?? {}),
+            },
+        }));
+        const results = await runSuite(adapter, selectedScenarios);
+        if (options.json) {
+            console.log(JSON.stringify({
+                adapter: adapter.name,
+                results,
+            }, null, 2));
+        }
+        else {
+            printResults(adapter.name, results);
+        }
+        if (options.junit) {
+            writeJUnit(options.junit, adapter.name, results);
+            console.log('JUnit report: ' + options.junit);
+        }
+        if (results.some((result) => !result.passed)) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error
+            ? error.message
+            : 'Unknown stable-ci error.');
+        process.exitCode = 2;
+    }
+});
+program.parseAsync();

package/dist/invariants/builtins.js

@@ -0,0 +1,138 @@
+const moneyEqual = (a, b) => Math.abs(a - b) < 0.005;
+function expectedStatuses(expected) {
+    if (expected.applicationStatus === undefined) {
+        return undefined;
+    }
+    return Array.isArray(expected.applicationStatus)
+        ? expected.applicationStatus
+        : [expected.applicationStatus];
+}
+export function evaluateInvariants(o, expected) {
+    const results = [];
+    if (expected.ledgerEntries !== undefined) {
+        const passed = o.ledgerEntries === expected.ledgerEntries;
+        results.push({
+            name: expected.ledgerEntries === 1
+                ? 'payment_posts_exactly_once'
+                : 'expected_ledger_entries',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected ' +
+                    expected.ledgerEntries +
+                    ' ledger entry/entries, observed ' +
+                    o.ledgerEntries +
+                    '.'
+        });
+    }
+    if (expected.credit === 'exact_expected') {
+        const passed = moneyEqual(o.creditedAmount, o.expectedAmount);
+        results.push({
+            name: 'ledger_delta_equals_settlement_amount',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected USD ' +
+                    o.expectedAmount.toFixed(2) +
+                    ', ledger credited USD ' +
+                    o.creditedAmount.toFixed(2) +
+                    '.'
+        });
+    }
+    if (expected.credit === 'none') {
+        const passed = moneyEqual(o.creditedAmount, 0);
+        results.push({
+            name: 'failed_payment_never_credits_balance',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected no credit, but USD ' +
+                    o.creditedAmount.toFixed(2) +
+                    ' was credited.'
+        });
+    }
+    if (expected.credit === 'received_amount') {
+        const hasReceivedAmount = o.receivedAmount !== undefined;
+        const passed = hasReceivedAmount &&
+            moneyEqual(o.creditedAmount, o.receivedAmount);
+        results.push({
+            name: 'ledger_delta_equals_received_amount',
+            passed,
+            message: passed
+                ? undefined
+                : hasReceivedAmount
+                    ? 'Expected received USD ' +
+                        o.receivedAmount.toFixed(2) +
+                        ', ledger credited USD ' +
+                        o.creditedAmount.toFixed(2) +
+                        '.'
+                    : 'Scenario did not report receivedAmount.'
+        });
+    }
+    const allowedStatuses = expectedStatuses(expected);
+    if (allowedStatuses !== undefined) {
+        const passed = allowedStatuses.includes(o.applicationStatus);
+        const completedOnly = allowedStatuses.length === 1 &&
+            allowedStatuses[0] === 'completed';
+        results.push({
+            name: completedOnly
+                ? 'confirmed_payment_must_end_completed'
+                : 'expected_application_status',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected application state ' +
+                    allowedStatuses.join(' or ') +
+                    ', observed ' +
+                    o.applicationStatus +
+                    '.'
+        });
+    }
+    if (expected.retryAttempts !== undefined) {
+        const passed = o.retryAttempts === expected.retryAttempts;
+        results.push({
+            name: expected.retryAttempts === 0
+                ? 'unknown_settlement_must_not_be_retried'
+                : 'expected_retry_attempts',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected ' +
+                    expected.retryAttempts +
+                    ' retry attempt(s), observed ' +
+                    o.retryAttempts +
+                    '.'
+        });
+    }
+    if (expected.webhookAccepted !== undefined) {
+        const passed = o.webhookAccepted === expected.webhookAccepted;
+        results.push({
+            name: expected.webhookAccepted === false
+                ? 'invalid_signature_must_be_rejected'
+                : 'expected_webhook_acceptance',
+            passed,
+            message: passed
+                ? undefined
+                : 'Expected webhookAccepted=' +
+                    expected.webhookAccepted +
+                    ', observed ' +
+                    String(o.webhookAccepted) +
+                    '.'
+        });
+    }
+    if (o.scenario === 'duplicate_webhook') {
+        const passed = o.webhookDeliveries <= 1 ||
+            o.ledgerEntries <= 1;
+        results.push({
+            name: 'duplicate_webhook_must_not_duplicate_ledger',
+            passed,
+            message: passed
+                ? undefined
+                : o.webhookDeliveries +
+                    ' webhook deliveries created ' +
+                    o.ledgerEntries +
+                    ' ledger entries.'
+        });
+    }
+    return results;
+}

package/dist/providers/bvnk.js

@@ -0,0 +1,60 @@
+import { createHmac } from 'node:crypto';
+function toBvnkStatus(status) {
+    switch (status) {
+        case 'pending':
+            return 'PROCESSING';
+        case 'completed':
+            return 'COMPLETE';
+        case 'failed':
+        case 'expired':
+            return 'EXPIRED';
+        case 'underpaid':
+            return 'UNDERPAID';
+    }
+}
+export function createBvnkProvider(webhookSecret = 'stable-ci-local-secret') {
+    return {
+        name: 'bvnk',
+        render(event) {
+            const eventType = event.eventType ?? 'statusChanged';
+            const actualAmount = event.actualAmount ?? event.amount;
+            const payload = {
+                source: 'payment',
+                event: eventType,
+                data: {
+                    uuid: event.paymentId,
+                    reference: event.eventId,
+                    type: 'IN',
+                    subType: 'merchantPayIn',
+                    status: toBvnkStatus(event.status),
+                    displayCurrency: {
+                        currency: event.asset,
+                        amount: event.amount,
+                        actual: actualAmount,
+                    },
+                    paidCurrency: {
+                        currency: event.asset,
+                        amount: event.amount,
+                        actual: actualAmount,
+                    },
+                    walletCurrency: {
+                        currency: event.asset,
+                        amount: event.amount,
+                        actual: actualAmount,
+                    },
+                },
+            };
+            const body = JSON.stringify(payload);
+            const signature = createHmac('sha256', webhookSecret)
+                .update(body, 'utf8')
+                .digest('base64');
+            return {
+                body,
+                headers: {
+                    'content-type': 'application/json',
+                    'x-signature': signature,
+                },
+            };
+        },
+    };
+}

package/dist/providers/generic.js

@@ -0,0 +1,13 @@
+export function createGenericProvider() {
+    return {
+        name: 'generic',
+        render(event) {
+            return {
+                body: JSON.stringify(event),
+                headers: {
+                    'content-type': 'application/json',
+                },
+            };
+        },
+    };
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/reporters/junit.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function failureText(result) {
+    return result.invariants
+        .filter((invariant) => !invariant.passed)
+        .map((invariant) => {
+        if (invariant.message) {
+            return invariant.name + ': ' + invariant.message;
+        }
+        return invariant.name;
+    })
+        .join('\n');
+}
+export function renderJUnit(adapterName, results) {
+    const failures = results.filter((result) => !result.passed).length;
+    const testcases = results.map((result) => {
+        const name = escapeXml(result.scenario.name);
+        const className = escapeXml('stable-ci.' + adapterName);
+        if (result.passed) {
+            return [
+                '  <testcase',
+                '    classname="' + className + '"',
+                '    name="' + name + '"',
+                '  />',
+            ].join('\n');
+        }
+        const message = failureText(result);
+        return [
+            '  <testcase',
+            '    classname="' + className + '"',
+            '    name="' + name + '"',
+            '  >',
+            '    <failure message="Stablecoin reliability invariant failed">',
+            escapeXml(message),
+            '    </failure>',
+            '  </testcase>',
+        ].join('\n');
+    });
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<testsuite',
+        '  name="stable-ci"',
+        '  tests="' + results.length + '"',
+        '  failures="' + failures + '"',
+        '>',
+        ...testcases,
+        '</testsuite>',
+        '',
+    ].join('\n');
+}
+export function writeJUnit(filePath, adapterName, results) {
+    const directory = path.dirname(path.resolve(filePath));
+    fs.mkdirSync(directory, {
+        recursive: true,
+    });
+    fs.writeFileSync(filePath, renderJUnit(adapterName, results), 'utf8');
+}

package/dist/scenarios/builtins.js

@@ -0,0 +1,106 @@
+export const scenarios = [
+    {
+        name: 'duplicate_webhook',
+        description: 'The same payment webhook is delivered more than once.',
+        risk: 'Duplicate ledger posting or duplicate credit',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+        },
+    },
+    {
+        name: 'out_of_order_webhook',
+        description: 'Payment lifecycle events arrive out of order.',
+        risk: 'State regression or incorrect final payment state',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+        },
+    },
+    {
+        name: 'missing_webhook',
+        description: 'The provider completes the payment but the webhook is never delivered.',
+        risk: 'Confirmed payment never reaches the internal ledger',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+        },
+    },
+    {
+        name: 'provider_timeout_after_broadcast',
+        description: 'The provider times out after broadcasting the transaction.',
+        risk: 'Unsafe retry can create a duplicate payment',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+            retryAttempts: 0,
+        },
+    },
+    {
+        name: 'late_chain_confirmation',
+        description: 'The chain confirms after the application has already observed a timeout.',
+        risk: 'Application and blockchain disagree about settlement',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+            retryAttempts: 0,
+        },
+    },
+    {
+        name: 'retry_after_unknown_settlement',
+        description: 'A retry is requested while the original settlement outcome is still unknown.',
+        risk: 'Double payment or duplicate payout',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+            retryAttempts: 0,
+        },
+    },
+    {
+        name: 'invalid_signature',
+        description: 'A webhook is delivered with an invalid provider signature.',
+        risk: 'Forged payment events may be accepted and credited',
+        expected: {
+            applicationStatus: 'none',
+            ledgerEntries: 0,
+            credit: 'none',
+            webhookAccepted: false,
+        },
+    },
+    {
+        name: 'underpayment',
+        description: 'The customer sends less than the requested payment amount.',
+        risk: 'Partial payment may be incorrectly treated as fully paid',
+        expected: {
+            applicationStatus: 'manual_review',
+            ledgerEntries: 0,
+            credit: 'none',
+        },
+    },
+    {
+        name: 'overpayment',
+        description: 'The customer sends more than the requested payment amount.',
+        risk: 'Excess funds may be incorrectly credited to the main customer balance',
+        expected: {
+            applicationStatus: 'completed',
+            ledgerEntries: 1,
+            credit: 'exact_expected',
+        },
+    },
+    {
+        name: 'late_payment',
+        description: 'Funds arrive after the original payment has already expired.',
+        risk: 'Expired payment may be incorrectly revived and credited as a normal payment',
+        expected: {
+            applicationStatus: 'manual_review',
+            ledgerEntries: 0,
+            credit: 'none',
+        },
+    },
+];

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "stable-ci",
+  "version": "0.1.0",
+  "description": "Reliability CI for stablecoin payment integrations",
+  "main": "index.js",
+  "scripts": {
+    "test": "vitest run",
+    "dev": "tsx src/index.ts",
+    "test:watch": "vitest",
+    "build": "tsc",
+    "check": "npm test && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "keywords": [
+    "stablecoin",
+    "payments",
+    "webhook",
+    "reliability",
+    "testing",
+    "ci",
+    "bvnk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "stable-ci": "dist/index.js"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saldfsdk/stable-ci.git"
+  },
+  "homepage": "https://github.com/saldfsdk/stable-ci#readme",
+  "bugs": {
+    "url": "https://github.com/saldfsdk/stable-ci/issues"
+  }
+}