stable-ci 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saldfsdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# stable-ci
+
+**Break your stablecoin integration before production.**
+
+`stable-ci` injects deterministic payment failures into stablecoin payment integrations and verifies that your application and ledger still converge to the expected financial state.
+
+It is designed for CI: define your payment policy, run failure scenarios against your integration, and fail the build when money moves incorrectly.
+
+## What it catches
+
+`stable-ci` currently tests:
+
+- Duplicate webhooks
+- Out-of-order webhooks
+- Missing webhooks
+- Provider timeout after broadcast
+- Late blockchain confirmation
+- Retry while settlement is unknown
+- Invalid webhook signatures
+- Underpayments
+- Overpayments
+- Late payments
+
+It verifies outcomes such as:
+
+- exactly-once ledger posting
+- credited amount
+- final application state
+- retry behavior
+- webhook acceptance
+- recovery after missing events
+
+## Example
+
+A broken overpayment handler:
+
+```text
+FAIL  overpayment
+      ledger_delta_equals_settlement_amount
+      Expected USD 100.00, ledger credited USD 140.00.
+```
+
+Instead of only asking whether an API request succeeded, `stable-ci` checks whether the resulting financial state is correct.
+
+## Install
+
+```bash
+npm install --save-dev stable-ci
+```
+
+Or run it directly:
+
+```bash
+npx stable-ci --help
+```
+
+## Quick start
+
+Create `stable-ci.yml`:
+
+```yaml
+provider: bvnk
+
+webhookSecret: your-test-webhook-secret
+
+target:
+  name: payment-app
+  baseUrl: http://127.0.0.1:4310
+  endpoints:
+    reset: /reset
+    webhook: /webhook
+    state: /state
+    reconcile: /reconcile
+
+payment:
+  id: pay_test_001
+  amount: 100
+  asset: USDC
+
+scenarios:
+  - duplicate_webhook
+  - out_of_order_webhook
+  - missing_webhook
+  - invalid_signature
+  - underpayment
+  - overpayment
+  - late_payment
+
+expectations:
+  underpayment:
+    applicationStatus: manual_review
+    ledgerEntries: 0
+    credit: none
+
+  overpayment:
+    applicationStatus: completed
+    ledgerEntries: 1
+    credit: exact_expected
+
+  late_payment:
+    applicationStatus: manual_review
+    ledgerEntries: 0
+    credit: none
+```
+
+Run:
+
+```bash
+npx stable-ci run --config stable-ci.yml
+```
+
+Example output:
+
+```text
+Stablecoin Reliability CI
+=========================
+Adapter: payment-app [bvnk]
+
+PASS  duplicate_webhook
+PASS  out_of_order_webhook
+PASS  missing_webhook
+PASS  invalid_signature
+PASS  underpayment
+FAIL  overpayment
+PASS  late_payment
+
+6 passed, 1 failed
+```
+
+A failed scenario causes a non-zero exit code, so it can fail CI.
+
+## Expected outcomes
+
+Different applications may intentionally handle payment exceptions differently.
+
+For example, an overpayment may credit only the requested amount:
+
+```yaml
+expectations:
+  overpayment:
+    applicationStatus: completed
+    ledgerEntries: 1
+    credit: exact_expected
+```
+
+While another application may intentionally credit the entire received amount:
+
+```yaml
+expectations:
+  overpayment:
+    applicationStatus: completed
+    ledgerEntries: 1
+    credit: received_amount
+```
+
+`stable-ci` tests against your declared financial policy instead of assuming that every integration has the same correct outcome.
+
+## GitHub Actions
+
+This repository includes a composite GitHub Action.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: saldfsdk/stable-ci@v0.1.0
+    with:
+      config: stable-ci.yml
+      junit: reports/stable-ci.xml
+```
+
+The action runs the configured scenarios and writes a JUnit report.
+
+## JUnit
+
+You can generate a JUnit XML report directly:
+
+```bash
+npx stable-ci run \
+  --config stable-ci.yml \
+  --junit reports/stable-ci.xml
+```
+
+JUnit reports are written even when reliability scenarios fail.
+
+## JSON output
+
+For machine-readable output:
+
+```bash
+npx stable-ci test --profile safe --json
+```
+
+## Built-in scenarios
+
+List all scenarios:
+
+```bash
+npx stable-ci scenarios
+```
+
+Current scenarios include:
+
+- `duplicate_webhook`
+- `out_of_order_webhook`
+- `missing_webhook`
+- `provider_timeout_after_broadcast`
+- `late_chain_confirmation`
+- `retry_after_unknown_settlement`
+- `invalid_signature`
+- `underpayment`
+- `overpayment`
+- `late_payment`
+
+## Provider support
+
+### BVNK
+
+The current BVNK adapter models payment webhook behavior including:
+
+- signed webhook delivery
+- `statusChanged`
+- `transactionConfirmed`
+- `transactionLate`
+- underpayments
+- overpayments
+- late payments
+
+Provider payload fixtures are based on publicly documented behavior and are intended for reliability testing.
+
+`stable-ci` is not affiliated with or endorsed by BVNK.
+
+### Generic
+
+A generic provider adapter is also included for provider-independent testing.
+
+## Architecture
+
+```text
+stable-ci.yml
+     |
+     v
+Scenario Runner
+     |
+     v
+Fault Injection
+     |
+     v
+Provider / Webhook / Application
+     |
+     v
+Observed State
+     |
+     v
+Expected Outcome + Invariant Engine
+     |
+     +---- PASS
+     |
+     +---- FAIL
+             |
+             +-- CLI
+             +-- JSON
+             +-- JUnit
+```
+
+## Why stable-ci?
+
+Payment integrations can fail even when individual API calls appear successful.
+
+Examples include:
+
+- the same webhook being delivered twice
+- lifecycle events arriving out of order
+- a payment being confirmed after an application timeout
+- retrying while settlement is still unknown
+- an invalid webhook being accepted
+- an underpayment being treated as fully paid
+- an overpayment being credited incorrectly
+- an expired payment being revived after late funds arrive
+
+These are not only API correctness problems.
+
+They are **money movement correctness** problems.
+
+`stable-ci` is designed to test the final financial outcome, not only whether a request returned HTTP 200.
+
+## Current status
+
+`stable-ci` is an early-stage developer tool.
+
+The current version focuses on deterministic local and CI testing.
+
+It does not yet provide full production blockchain observation or hosted monitoring.
+
+Planned areas include:
+
+- additional provider adapters
+- richer CI reporting
+- blockchain/RPC observers
+- provider sandbox drift detection
+- hosted reliability testing
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run all tests and build:
+
+```bash
+npm run check
+```
+
+Run the local safe demo:
+
+```bash
+npm run build
+node dist/index.js test-http --profile safe
+```
+
+Expected result:
+
+```text
+10 passed, 0 failed
+```
+
+Run the intentionally unsafe demo:
+
+```bash
+node dist/index.js test-http --profile unsafe
+```
+
+Expected result:
+
+```text
+0 passed, 10 failed
+```
+
+The unsafe profile intentionally contains broken payment-handling behavior so that the reliability checks can demonstrate what they detect.
+
+## License
+
+MIT

package/dist/adapters/configured-http.js

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { createBvnkProvider } from '../providers/bvnk.js';
+import { createGenericProvider } from '../providers/generic.js';
+const stateSchema = z.object({
+    applicationStatus: z.enum([
+        'none',
+        'pending',
+        'completed',
+        'failed',
+        'manual_review',
+    ]),
+    webhookDeliveries: z.number(),
+    ledgerEntries: z.number(),
+    creditedAmount: z.number(),
+    retryAttempts: z.number().default(0),
+    settlementWasUnknown: z.boolean().default(false),
+    recovered: z.boolean().default(false),
+});
+function getProvider(config) {
+    if (config.provider === 'bvnk') {
+        return createBvnkProvider(config.webhookSecret ?? 'stable-ci-local-secret');
+    }
+    return createGenericProvider();
+}
+async function postJson(baseUrl, path, body = {}) {
+    const response = await fetch(baseUrl + path, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error('HTTP ' + response.status + ' from ' + path);
+    }
+}
+async function sendWebhook(config, provider, eventId, status, actualAmount, eventType) {
+    const rendered = provider.render({
+        eventId,
+        paymentId: config.payment.id,
+        status,
+        amount: config.payment.amount,
+        asset: config.payment.asset,
+        actualAmount,
+        eventType,
+    });
+    const response = await fetch(config.target.baseUrl +
+        config.target.endpoints.webhook, {
+        method: 'POST',
+        headers: rendered.headers,
+        body: rendered.body,
+    });
+    if (!response.ok) {
+        throw new Error('Webhook returned HTTP ' + response.status);
+    }
+    return response.status;
+}
+async function sendInvalidSignatureWebhook(config, provider) {
+    const rendered = provider.render({
+        eventId: 'evt_invalid_signature',
+        paymentId: config.payment.id,
+        status: 'completed',
+        amount: config.payment.amount,
+        asset: config.payment.asset,
+    });
+    const response = await fetch(config.target.baseUrl +
+        config.target.endpoints.webhook, {
+        method: 'POST',
+        headers: {
+            ...rendered.headers,
+            'x-signature': 'invalid-signature',
+        },
+        body: rendered.body,
+    });
+    return response.ok;
+}
+async function getState(config) {
+    const response = await fetch(config.target.baseUrl +
+        config.target.endpoints.state);
+    if (!response.ok) {
+        throw new Error('Failed to read target application state.');
+    }
+    return stateSchema.parse(await response.json());
+}
+export function createConfiguredHttpAdapter(config) {
+    const provider = getProvider(config);
+    return {
+        name: config.target.name + ' [' + provider.name + ']',
+        async runScenario(scenario) {
+            const baseUrl = config.target.baseUrl;
+            const endpoints = config.target.endpoints;
+            const payment = config.payment;
+            await postJson(baseUrl, endpoints.reset);
+            let providerStatus = 'completed';
+            let chainStatus = 'confirmed';
+            let webhookAccepted;
+            let receivedAmount;
+            switch (scenario) {
+                case 'duplicate_webhook':
+                    await sendWebhook(config, provider, 'evt_complete_1', 'completed');
+                    await sendWebhook(config, provider, 'evt_complete_1', 'completed');
+                    break;
+                case 'out_of_order_webhook':
+                    await sendWebhook(config, provider, 'evt_complete_1', 'completed');
+                    await sendWebhook(config, provider, 'evt_pending_2', 'pending');
+                    break;
+                case 'missing_webhook':
+                    if (endpoints.reconcile) {
+                        await postJson(baseUrl, endpoints.reconcile, {
+                            paymentId: payment.id,
+                            chainStatus: 'confirmed',
+                            amount: payment.amount,
+                            asset: payment.asset,
+                        });
+                    }
+                    break;
+                case 'invalid_signature':
+                    if (provider.name !== 'bvnk') {
+                        throw new Error('invalid_signature currently requires the BVNK provider.');
+                    }
+                    webhookAccepted =
+                        await sendInvalidSignatureWebhook(config, provider);
+                    providerStatus = 'failed';
+                    chainStatus = 'not_broadcast';
+                    break;
+                case 'underpayment':
+                    if (provider.name !== 'bvnk') {
+                        throw new Error('underpayment currently requires the BVNK provider.');
+                    }
+                    receivedAmount = payment.amount * 0.6;
+                    providerStatus = 'underpaid';
+                    await sendWebhook(config, provider, 'evt_underpayment_1', 'underpaid', receivedAmount, 'transactionConfirmed');
+                    break;
+                case 'overpayment':
+                    if (provider.name !== 'bvnk') {
+                        throw new Error('overpayment currently requires the BVNK provider.');
+                    }
+                    receivedAmount = payment.amount * 1.4;
+                    providerStatus = 'completed';
+                    await sendWebhook(config, provider, 'evt_overpayment_1', 'completed', receivedAmount, 'transactionConfirmed');
+                    break;
+                case 'late_payment':
+                    if (provider.name !== 'bvnk') {
+                        throw new Error('late_payment currently requires the BVNK provider.');
+                    }
+                    receivedAmount = payment.amount;
+                    providerStatus = 'expired';
+                    await sendWebhook(config, provider, 'evt_late_payment_1', 'expired', receivedAmount, 'transactionLate');
+                    break;
+                default:
+                    throw new Error('Scenario is not supported by the configured HTTP adapter yet: ' +
+                        scenario);
+            }
+            const state = await getState(config);
+            return {
+                scenario,
+                paymentId: payment.id,
+                expectedAmount: payment.amount,
+                receivedAmount,
+                providerStatus,
+                chainStatus,
+                webhookDeliveries: state.webhookDeliveries,
+                ledgerEntries: state.ledgerEntries,
+                creditedAmount: state.creditedAmount,
+                applicationStatus: state.applicationStatus,
+                retryAttempts: state.retryAttempts,
+                settlementWasUnknown: state.settlementWasUnknown,
+                recovered: state.recovered,
+                webhookAccepted,
+            };
+        },
+    };
+}

package/dist/adapters/demo.js

@@ -0,0 +1,150 @@
+const baseObservation = (scenario) => ({
+    scenario,
+    paymentId: 'pay_demo_001',
+    expectedAmount: 100,
+    providerStatus: 'completed',
+    chainStatus: 'confirmed',
+    webhookDeliveries: 1,
+    ledgerEntries: 1,
+    creditedAmount: 100,
+    applicationStatus: 'completed',
+    retryAttempts: 0,
+    settlementWasUnknown: false,
+    recovered: false,
+});
+function safeObservation(scenario) {
+    const o = baseObservation(scenario);
+    switch (scenario) {
+        case 'duplicate_webhook':
+            return {
+                ...o,
+                webhookDeliveries: 2,
+            };
+        case 'out_of_order_webhook':
+            return {
+                ...o,
+                webhookDeliveries: 3,
+            };
+        case 'missing_webhook':
+            return {
+                ...o,
+                webhookDeliveries: 0,
+                recovered: true,
+            };
+        case 'provider_timeout_after_broadcast':
+        case 'late_chain_confirmation':
+        case 'retry_after_unknown_settlement':
+            return {
+                ...o,
+                providerStatus: 'timeout',
+                webhookDeliveries: 0,
+                settlementWasUnknown: true,
+                recovered: true,
+            };
+        case 'invalid_signature':
+            return {
+                ...o,
+                providerStatus: 'failed',
+                chainStatus: 'not_broadcast',
+                applicationStatus: 'none',
+                webhookDeliveries: 0,
+                ledgerEntries: 0,
+                creditedAmount: 0,
+                webhookAccepted: false,
+            };
+        case 'late_payment':
+            return {
+                ...o,
+                providerStatus: 'expired',
+                receivedAmount: 100,
+                applicationStatus: 'manual_review',
+                ledgerEntries: 0,
+                creditedAmount: 0,
+            };
+        case 'overpayment':
+            return {
+                ...o,
+                receivedAmount: 140,
+            };
+        case 'underpayment':
+            return {
+                ...o,
+                providerStatus: 'underpaid',
+                receivedAmount: 60,
+                applicationStatus: 'manual_review',
+                ledgerEntries: 0,
+                creditedAmount: 0,
+            };
+    }
+}
+function unsafeObservation(scenario) {
+    const safe = safeObservation(scenario);
+    switch (scenario) {
+        case 'duplicate_webhook':
+            return {
+                ...safe,
+                ledgerEntries: 2,
+                creditedAmount: 200,
+            };
+        case 'out_of_order_webhook':
+            return {
+                ...safe,
+                applicationStatus: 'pending',
+            };
+        case 'missing_webhook':
+            return {
+                ...safe,
+                applicationStatus: 'none',
+                ledgerEntries: 0,
+                creditedAmount: 0,
+            };
+        case 'provider_timeout_after_broadcast':
+        case 'late_chain_confirmation':
+        case 'retry_after_unknown_settlement':
+            return {
+                ...safe,
+                retryAttempts: 1,
+                ledgerEntries: 2,
+                creditedAmount: 200,
+            };
+        case 'invalid_signature':
+            return {
+                ...safe,
+                applicationStatus: 'completed',
+                webhookDeliveries: 1,
+                ledgerEntries: 1,
+                creditedAmount: 100,
+                webhookAccepted: true,
+            };
+        case 'late_payment':
+            return {
+                ...safe,
+                applicationStatus: 'completed',
+                ledgerEntries: 1,
+                creditedAmount: 100,
+            };
+        case 'overpayment':
+            return {
+                ...safe,
+                receivedAmount: 140,
+                creditedAmount: 140,
+            };
+        case 'underpayment':
+            return {
+                ...safe,
+                applicationStatus: 'completed',
+                ledgerEntries: 1,
+                creditedAmount: 100,
+            };
+    }
+}
+export function createDemoAdapter(profile) {
+    return {
+        name: 'demo:' + profile,
+        async runScenario(scenario) {
+            return profile === 'safe'
+                ? safeObservation(scenario)
+                : unsafeObservation(scenario);
+        },
+    };
+}