nirium 0.16.1 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -7
- package/dist/index.d.ts +24 -3
- package/dist/index.js +48 -5
- package/dist/x402-policy-conformance.d.ts +64 -0
- package/dist/x402-policy-conformance.js +269 -0
- package/dist/x402-spend-cap.js +2 -2
- package/package.json +18 -1
- package/dist/metrics.test.d.ts +0 -1
- package/dist/metrics.test.js +0 -614
- package/dist/x402-guard.test.d.ts +0 -11
- package/dist/x402-guard.test.js +0 -145
- package/dist/x402serve-smoke.test.d.ts +0 -9
- package/dist/x402serve-smoke.test.js +0 -158
package/dist/x402-guard.test.js
DELETED
|
@@ -1,145 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/**
|
|
3
|
-
* Unit tests for the replay guard / rate limit checks that back
|
|
4
|
-
* X402ServeConfig['guard']. Pure functions against a fake in-memory store,
|
|
5
|
-
* no network or Express involved — the integration-level tests (guard
|
|
6
|
-
* wired through x402Serve() itself) live in x402serve-smoke.test.ts.
|
|
7
|
-
*
|
|
8
|
-
* These reproduce the exact scenarios a real production x402Serve() user
|
|
9
|
-
* (Edgadafi/remesa-liquidez) built their own version of this against, per
|
|
10
|
-
* https://github.com/nirium-protocol/nirium/issues/91.
|
|
11
|
-
*/
|
|
12
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
13
|
-
const x402_guard_1 = require("./x402-guard");
|
|
14
|
-
function fakeStore() {
|
|
15
|
-
const claims = new Map();
|
|
16
|
-
return {
|
|
17
|
-
claims,
|
|
18
|
-
async claimOnce(key, ttlMs) {
|
|
19
|
-
const now = Date.now();
|
|
20
|
-
const expiresAt = claims.get(key);
|
|
21
|
-
if (expiresAt !== undefined && expiresAt > now)
|
|
22
|
-
return false;
|
|
23
|
-
claims.set(key, now + ttlMs);
|
|
24
|
-
return true;
|
|
25
|
-
},
|
|
26
|
-
async release(key) {
|
|
27
|
-
claims.delete(key);
|
|
28
|
-
},
|
|
29
|
-
async slidingWindowHit() {
|
|
30
|
-
throw new Error('slidingWindowHit not used by replay tests');
|
|
31
|
-
},
|
|
32
|
-
};
|
|
33
|
-
}
|
|
34
|
-
function req(overrides = {}) {
|
|
35
|
-
return {
|
|
36
|
-
method: 'GET',
|
|
37
|
-
url: '/signals',
|
|
38
|
-
headers: { 'payment-signature': 'proof-abc' },
|
|
39
|
-
ip: '203.0.113.1',
|
|
40
|
-
...overrides,
|
|
41
|
-
};
|
|
42
|
-
}
|
|
43
|
-
describe('checkReplay', () => {
|
|
44
|
-
it('allows a request with no payment proof yet (lets x402Serve issue its 402)', async () => {
|
|
45
|
-
const store = fakeStore();
|
|
46
|
-
const config = { store };
|
|
47
|
-
const result = await (0, x402_guard_1.checkReplay)(req({ headers: {} }), config);
|
|
48
|
-
expect(result.allowed).toBe(true);
|
|
49
|
-
});
|
|
50
|
-
it('allows the first use of a payment proof', async () => {
|
|
51
|
-
const store = fakeStore();
|
|
52
|
-
const config = { store };
|
|
53
|
-
const result = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
54
|
-
expect(result.allowed).toBe(true);
|
|
55
|
-
expect(store.claims.size).toBe(1);
|
|
56
|
-
});
|
|
57
|
-
it('rejects a reused payment proof against the same route with 409', async () => {
|
|
58
|
-
const store = fakeStore();
|
|
59
|
-
const config = { store };
|
|
60
|
-
const first = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
61
|
-
expect(first.allowed).toBe(true);
|
|
62
|
-
const second = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
63
|
-
expect(second.allowed).toBe(false);
|
|
64
|
-
expect(second.denied?.status).toBe(409);
|
|
65
|
-
expect(second.denied?.body.error).toBe('payment_replayed');
|
|
66
|
-
});
|
|
67
|
-
it('allows the same proof against a DIFFERENT route (binds proof + method + route)', async () => {
|
|
68
|
-
const store = fakeStore();
|
|
69
|
-
const config = { store };
|
|
70
|
-
await (0, x402_guard_1.checkReplay)(req({ url: '/signals' }), config);
|
|
71
|
-
const other = await (0, x402_guard_1.checkReplay)(req({ url: '/market' }), config);
|
|
72
|
-
expect(other.allowed).toBe(true);
|
|
73
|
-
});
|
|
74
|
-
it('reads the x402 v2 header "payment-signature" and the v1 fallback "x-payment"', async () => {
|
|
75
|
-
const store = fakeStore();
|
|
76
|
-
const config = { store };
|
|
77
|
-
const v2 = await (0, x402_guard_1.checkReplay)(req({ headers: { 'payment-signature': 'same-proof' } }), config);
|
|
78
|
-
expect(v2.allowed).toBe(true);
|
|
79
|
-
const v1Reuse = await (0, x402_guard_1.checkReplay)(req({ headers: { 'x-payment': 'same-proof' } }), config);
|
|
80
|
-
// Same underlying proof string, same method+url -> same digest -> replay.
|
|
81
|
-
expect(v1Reuse.allowed).toBe(false);
|
|
82
|
-
});
|
|
83
|
-
it('releases the claim when the caller reports the request did not succeed, allowing a legitimate retry', async () => {
|
|
84
|
-
const store = fakeStore();
|
|
85
|
-
const config = { store };
|
|
86
|
-
const first = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
87
|
-
expect(first.allowed).toBe(true);
|
|
88
|
-
await first.release(); // simulates: response ended non-2xx (e.g. facilitator down)
|
|
89
|
-
const retry = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
90
|
-
expect(retry.allowed).toBe(true);
|
|
91
|
-
});
|
|
92
|
-
it('fails CLOSED (503) when the store is unavailable, never silently letting the payment through unprotected', async () => {
|
|
93
|
-
const brokenStore = {
|
|
94
|
-
async claimOnce() { throw new Error('store down'); },
|
|
95
|
-
async release() { },
|
|
96
|
-
async slidingWindowHit() { throw new Error('store down'); },
|
|
97
|
-
};
|
|
98
|
-
const config = { store: brokenStore };
|
|
99
|
-
const result = await (0, x402_guard_1.checkReplay)(req(), config);
|
|
100
|
-
expect(result.allowed).toBe(false);
|
|
101
|
-
expect(result.denied?.status).toBe(503);
|
|
102
|
-
expect(result.denied?.body.error).toBe('replay_protection_unavailable');
|
|
103
|
-
});
|
|
104
|
-
});
|
|
105
|
-
describe('checkRateLimit', () => {
|
|
106
|
-
it('allows when no rateLimit config is set, even with a store present', async () => {
|
|
107
|
-
const store = fakeStore();
|
|
108
|
-
const config = { store };
|
|
109
|
-
const result = await (0, x402_guard_1.checkRateLimit)(req(), config);
|
|
110
|
-
expect(result.allowed).toBe(true);
|
|
111
|
-
});
|
|
112
|
-
it('allows requests under the limit', async () => {
|
|
113
|
-
let hits = 0;
|
|
114
|
-
const store = {
|
|
115
|
-
async claimOnce() { return true; },
|
|
116
|
-
async release() { },
|
|
117
|
-
async slidingWindowHit() { hits += 1; return hits; },
|
|
118
|
-
};
|
|
119
|
-
const config = { store, rateLimit: { max: 5, windowMs: 60_000 } };
|
|
120
|
-
const result = await (0, x402_guard_1.checkRateLimit)(req(), config);
|
|
121
|
-
expect(result.allowed).toBe(true);
|
|
122
|
-
});
|
|
123
|
-
it('rejects with 429 once the sliding window count exceeds max', async () => {
|
|
124
|
-
const store = {
|
|
125
|
-
async claimOnce() { return true; },
|
|
126
|
-
async release() { },
|
|
127
|
-
async slidingWindowHit() { return 6; },
|
|
128
|
-
};
|
|
129
|
-
const config = { store, rateLimit: { max: 5, windowMs: 60_000 } };
|
|
130
|
-
const result = await (0, x402_guard_1.checkRateLimit)(req(), config);
|
|
131
|
-
expect(result.allowed).toBe(false);
|
|
132
|
-
expect(result.denied?.status).toBe(429);
|
|
133
|
-
expect(result.denied?.headers?.['Retry-After']).toBe('60');
|
|
134
|
-
});
|
|
135
|
-
it('fails OPEN when the store errors, so a store outage never becomes a self-inflicted denial of service', async () => {
|
|
136
|
-
const store = {
|
|
137
|
-
async claimOnce() { return true; },
|
|
138
|
-
async release() { },
|
|
139
|
-
async slidingWindowHit() { throw new Error('store down'); },
|
|
140
|
-
};
|
|
141
|
-
const config = { store, rateLimit: { max: 5, windowMs: 60_000 } };
|
|
142
|
-
const result = await (0, x402_guard_1.checkRateLimit)(req(), config);
|
|
143
|
-
expect(result.allowed).toBe(true);
|
|
144
|
-
});
|
|
145
|
-
});
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Smoke tests for x402Serve — verifies synchronous validation is intact.
|
|
3
|
-
*
|
|
4
|
-
* These tests do NOT call the real middleware (which dynamically imports
|
|
5
|
-
* @x402/express, @x402/core, and @x402/stellar at first request). They only
|
|
6
|
-
* verify that x402Serve rejects bad config the same way with or without the
|
|
7
|
-
* metrics wrapper applied.
|
|
8
|
-
*/
|
|
9
|
-
export {};
|
|
@@ -1,158 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/**
|
|
3
|
-
* Smoke tests for x402Serve — verifies synchronous validation is intact.
|
|
4
|
-
*
|
|
5
|
-
* These tests do NOT call the real middleware (which dynamically imports
|
|
6
|
-
* @x402/express, @x402/core, and @x402/stellar at first request). They only
|
|
7
|
-
* verify that x402Serve rejects bad config the same way with or without the
|
|
8
|
-
* metrics wrapper applied.
|
|
9
|
-
*/
|
|
10
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
-
// Mock all ESM-only dependencies before importing index.ts
|
|
12
|
-
jest.mock('ws', () => ({ default: class WS {
|
|
13
|
-
}, WebSocket: class WS {
|
|
14
|
-
} }));
|
|
15
|
-
jest.mock('@x402/fetch', () => ({
|
|
16
|
-
x402Client: class {
|
|
17
|
-
},
|
|
18
|
-
wrapFetchWithPayment: () => (url, init) => fetch(url, init),
|
|
19
|
-
}));
|
|
20
|
-
jest.mock('@x402/stellar', () => ({
|
|
21
|
-
createEd25519Signer: () => ({
|
|
22
|
-
address: 'GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF',
|
|
23
|
-
signAuthEntry: async () => ({ signedAuthEntry: 'mock' }),
|
|
24
|
-
}),
|
|
25
|
-
}));
|
|
26
|
-
jest.mock('@x402/stellar/exact/client', () => ({
|
|
27
|
-
ExactStellarScheme: class {
|
|
28
|
-
},
|
|
29
|
-
}));
|
|
30
|
-
jest.mock('mppx/client', () => ({
|
|
31
|
-
Mppx: { create: () => ({ fetch: async () => new Response('{}') }) },
|
|
32
|
-
}));
|
|
33
|
-
jest.mock('@stellar/mpp/charge/client', () => ({
|
|
34
|
-
stellar: { charge: () => ({}) },
|
|
35
|
-
}));
|
|
36
|
-
// stellar-sdk 16 loads ESM-only @noble/hashes; index.ts pulls it in through
|
|
37
|
-
// x402-policy.ts. Only the constants read at module load are needed here.
|
|
38
|
-
jest.mock('@stellar/stellar-sdk', () => ({
|
|
39
|
-
Networks: { TESTNET: 'Test SDF Network ; September 2015', PUBLIC: 'Public Global Stellar Network ; September 2015' },
|
|
40
|
-
}));
|
|
41
|
-
const index_1 = require("./index");
|
|
42
|
-
const metrics_1 = require("./metrics");
|
|
43
|
-
const VALID_CONFIG = {
|
|
44
|
-
payTo: 'GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF',
|
|
45
|
-
routes: { 'GET /signals': '$0.02' },
|
|
46
|
-
facilitatorApiKey: 'oz_test_key',
|
|
47
|
-
};
|
|
48
|
-
describe('x402Serve smoke', () => {
|
|
49
|
-
it('returns a function with the expected middleware signature', () => {
|
|
50
|
-
const handler = (0, index_1.x402Serve)(VALID_CONFIG);
|
|
51
|
-
expect(typeof handler).toBe('function');
|
|
52
|
-
expect(handler.length).toBe(3); // (req, res, next)
|
|
53
|
-
});
|
|
54
|
-
it('throws on missing payTo', () => {
|
|
55
|
-
expect(() => (0, index_1.x402Serve)({ ...VALID_CONFIG, payTo: '' })).toThrow('payTo');
|
|
56
|
-
});
|
|
57
|
-
it('throws on invalid payTo format', () => {
|
|
58
|
-
expect(() => (0, index_1.x402Serve)({ ...VALID_CONFIG, payTo: 'not-a-stellar-key' })).toThrow('payTo');
|
|
59
|
-
});
|
|
60
|
-
it('throws on empty routes', () => {
|
|
61
|
-
expect(() => (0, index_1.x402Serve)({ ...VALID_CONFIG, routes: {} })).toThrow('routes');
|
|
62
|
-
});
|
|
63
|
-
it('throws when neither facilitatorApiKey nor facilitatorUrl is provided', () => {
|
|
64
|
-
expect(() => (0, index_1.x402Serve)({
|
|
65
|
-
payTo: VALID_CONFIG.payTo,
|
|
66
|
-
routes: VALID_CONFIG.routes,
|
|
67
|
-
})).toThrow('facilitatorApiKey');
|
|
68
|
-
});
|
|
69
|
-
});
|
|
70
|
-
describe('x402Metrics wrapping x402Serve', () => {
|
|
71
|
-
it('wraps without changing the handler shape', () => {
|
|
72
|
-
const inner = (0, index_1.x402Serve)(VALID_CONFIG);
|
|
73
|
-
const { handler, metricsHandler } = (0, metrics_1.x402Metrics)(inner);
|
|
74
|
-
expect(typeof handler).toBe('function');
|
|
75
|
-
expect(handler.length).toBe(3);
|
|
76
|
-
expect(typeof metricsHandler).toBe('function');
|
|
77
|
-
});
|
|
78
|
-
it('does not intercept synchronous validation errors', () => {
|
|
79
|
-
// Bad config — x402Serve throws synchronously before the wrapper
|
|
80
|
-
// ever sees it. This proves the wrapper doesn't swallow errors.
|
|
81
|
-
expect(() => (0, metrics_1.x402Metrics)((0, index_1.x402Serve)({ ...VALID_CONFIG, payTo: '' }))).toThrow('payTo');
|
|
82
|
-
});
|
|
83
|
-
});
|
|
84
|
-
describe('x402Serve guard integration (config.guard)', () => {
|
|
85
|
-
// These only exercise the DENIED paths (409/503/429), which return before
|
|
86
|
-
// x402Serve ever reaches preflight()/build() — so none of this needs the
|
|
87
|
-
// @x402/express/@x402/core mocks above. The allowed-path/store behavior
|
|
88
|
-
// itself is covered directly in x402-guard.test.ts.
|
|
89
|
-
function fakeStore(overrides = {}) {
|
|
90
|
-
return {
|
|
91
|
-
claimOnce: overrides.claimOnce ?? (async () => true),
|
|
92
|
-
release: overrides.release ?? (async () => { }),
|
|
93
|
-
slidingWindowHit: overrides.slidingWindowHit ?? (async () => 1),
|
|
94
|
-
};
|
|
95
|
-
}
|
|
96
|
-
function mockReqRes(headers = {}) {
|
|
97
|
-
const req = { method: 'GET', url: '/signals', originalUrl: '/signals', headers, ip: '203.0.113.1' };
|
|
98
|
-
const res = {
|
|
99
|
-
statusCode: 200,
|
|
100
|
-
status(code) { this.statusCode = code; return this; },
|
|
101
|
-
json(body) { this.body = body; return this; },
|
|
102
|
-
setHeader(k, v) { this.headers = { ...(this.headers ?? {}), [k]: v }; },
|
|
103
|
-
on() { },
|
|
104
|
-
};
|
|
105
|
-
return { req, res };
|
|
106
|
-
}
|
|
107
|
-
it('rejects a reused X-PAYMENT the same way Edgadafi/remesa-liquidez does: 409, payment_replayed', async () => {
|
|
108
|
-
const store = fakeStore({
|
|
109
|
-
claimOnce: (() => {
|
|
110
|
-
let used = false;
|
|
111
|
-
return async () => { if (used)
|
|
112
|
-
return false; used = true; return true; };
|
|
113
|
-
})(),
|
|
114
|
-
});
|
|
115
|
-
const handler = (0, index_1.x402Serve)({ ...VALID_CONFIG, guard: { store } });
|
|
116
|
-
const first = mockReqRes({ 'payment-signature': 'proof-1' });
|
|
117
|
-
await handler(first.req, first.res, () => { });
|
|
118
|
-
// First call proceeds past the guard (into preflight, which will fail
|
|
119
|
-
// in this test env with no real facilitator — that's fine, it's not
|
|
120
|
-
// what this test is checking).
|
|
121
|
-
const second = mockReqRes({ 'payment-signature': 'proof-1' });
|
|
122
|
-
await handler(second.req, second.res, () => { });
|
|
123
|
-
expect(second.res.statusCode).toBe(409);
|
|
124
|
-
expect(second.res.body.error).toBe('payment_replayed');
|
|
125
|
-
});
|
|
126
|
-
it('responds 503 instead of accepting a payment unprotected when the guard store is down', async () => {
|
|
127
|
-
const store = fakeStore({ claimOnce: async () => { throw new Error('store down'); } });
|
|
128
|
-
const handler = (0, index_1.x402Serve)({ ...VALID_CONFIG, guard: { store } });
|
|
129
|
-
const { req, res } = mockReqRes({ 'payment-signature': 'proof-2' });
|
|
130
|
-
await handler(req, res, () => { });
|
|
131
|
-
expect(res.statusCode).toBe(503);
|
|
132
|
-
expect(res.body.error).toBe('replay_protection_unavailable');
|
|
133
|
-
});
|
|
134
|
-
it('rate-limits with 429 before ever looking at the payment proof', async () => {
|
|
135
|
-
const store = fakeStore({ slidingWindowHit: async () => 999 });
|
|
136
|
-
const handler = (0, index_1.x402Serve)({
|
|
137
|
-
...VALID_CONFIG,
|
|
138
|
-
guard: { store, rateLimit: { max: 5, windowMs: 60_000 } },
|
|
139
|
-
});
|
|
140
|
-
const { req, res } = mockReqRes({ 'payment-signature': 'proof-3' });
|
|
141
|
-
await handler(req, res, () => { });
|
|
142
|
-
expect(res.statusCode).toBe(429);
|
|
143
|
-
expect(res.body.error).toBe('rate_limited');
|
|
144
|
-
expect(res.headers['Retry-After']).toBe('60');
|
|
145
|
-
});
|
|
146
|
-
it('with no `guard` config at all, behaves exactly as before (no 409/503/429 from the guard layer)', async () => {
|
|
147
|
-
const handler = (0, index_1.x402Serve)(VALID_CONFIG); // no `guard` key
|
|
148
|
-
const first = mockReqRes({ 'payment-signature': 'proof-4' });
|
|
149
|
-
await handler(first.req, first.res, () => { });
|
|
150
|
-
const second = mockReqRes({ 'payment-signature': 'proof-4' }); // same "proof" reused
|
|
151
|
-
await handler(second.req, second.res, () => { });
|
|
152
|
-
// Neither call was rejected by a guard that doesn't exist - whatever
|
|
153
|
-
// status they got came from downstream (preflight failing in this test
|
|
154
|
-
// env), never 409/429, and never our guard's own error bodies.
|
|
155
|
-
expect(second.res.body?.error).not.toBe('payment_replayed');
|
|
156
|
-
expect(second.res.statusCode).not.toBe(409);
|
|
157
|
-
});
|
|
158
|
-
});
|