A local-first personal finance app
import { format } from 'node:util';
import createDebug from 'debug';
import request from 'supertest';
import * as undici from 'undici';
import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { handlers as app, clearAllowlistCache } from './app-cors-proxy';
import { config } from './load-config';
import { validateSession } from './util/validate-user';
vi.mock('undici', async importOriginal => ({
...(await importOriginal()),
fetch: vi.fn(),
}));
vi.mock('./load-config', () => ({
config: {
get: vi.fn(),
},
}));
vi.mock('./util/middlewares', () => ({
requestLoggerMiddleware: (req, res, next) => next(),
}));
vi.mock('./util/validate-user', () => ({
validateSession: vi.fn(),
}));
vi.mock('express-rate-limit', () => ({
default: vi.fn(() => (req, res, next) => next()),
}));
describe('app-cors-proxy', () => {
const defaultAllowlistedRepos = [
'https://github.com/user/repo1',
'https://github.com/user/repo2',
];
const createFetchMock = (options = {}) => {
const {
allowlistedRepos = defaultAllowlistedRepos,
allowlistFetchFails = false,
allowlistHttpError = false,
proxyResponses = {},
} = options;
return vi.fn().mockImplementation((url, _requestOptions) => {
if (
url ===
'https://raw.githubusercontent.com/actualbudget/plugin-store/refs/heads/main/plugins.json'
) {
if (allowlistFetchFails) {
return Promise.reject(new Error('Network error'));
}
if (allowlistHttpError) {
return Promise.resolve({
ok: false,
status: 404,
});
}
return Promise.resolve({
ok: true,
json: () =>
Promise.resolve(
allowlistedRepos.map(repoUrl => ({ url: repoUrl })),
),
});
}
if (proxyResponses[url]) {
const response = proxyResponses[url];
if (response.error) {
return Promise.reject(response.error);
}
return Promise.resolve(response);
}
return Promise.resolve({
ok: true,
text: () => Promise.resolve('default response'),
headers: {
get: () => 'text/plain',
},
status: 200,
});
});
};
const comprehensiveProxyResponses = {
'https://github.com/user/repo1': {
ok: true,
text: () => Promise.resolve('test content'),
headers: { get: () => 'text/plain' },
status: 200,
},
'https://api.github.com/repos/user/repo1/releases': {
ok: true,
text: () => Promise.resolve('{"name": "test"}'),
headers: { get: () => 'application/json' },
status: 200,
},
'https://api.github.com/repos/user/repo1': {
ok: true,
text: () => Promise.resolve('{"name": "repo1"}'),
headers: { get: () => 'application/json' },
status: 200,
},
'https://raw.githubusercontent.com/user/repo1/main/file.txt': {
ok: true,
text: () => Promise.resolve('file content'),
headers: { get: () => 'text/plain' },
status: 200,
},
'https://github.com/user/repo1/releases/download/v1.0.0/file.zip': {
ok: true,
arrayBuffer: () =>
Promise.resolve(new TextEncoder().encode('release content').buffer),
headers: { get: () => 'application/octet-stream' },
status: 200,
},
'https://github.com/user/repo1/manifest.json': {
ok: true,
text: () =>
Promise.resolve(JSON.stringify({ name: 'test', version: '1.0.0' })),
headers: { get: () => 'application/json' },
status: 200,
},
'https://github.com/user/repo1/package.json': {
ok: true,
text: () => Promise.resolve(JSON.stringify({ test: true })),
headers: { get: () => 'text/plain' },
status: 200,
},
'https://github.com/user/repo1/readme.txt': {
ok: true,
text: () => Promise.resolve('Hello, world!'),
headers: { get: () => 'text/plain' },
status: 200,
},
'https://github.com/user/repo1/file.bin': {
ok: true,
arrayBuffer: () =>
Promise.resolve(new Uint8Array([1, 2, 3, 4, 5]).buffer),
headers: { get: () => 'application/octet-stream' },
status: 200,
},
'https://github.com/user/repo1/invalid.json': {
ok: true,
text: () => Promise.resolve('not valid json'),
headers: { get: () => 'text/plain' },
status: 200,
},
'https://github.com/user/repo1/network-error': {
error: new Error('Network error'),
},
};
beforeAll(() => {
vi.mocked(undici.fetch).mockImplementation(
createFetchMock({
proxyResponses: comprehensiveProxyResponses,
}),
);
});
beforeEach(() => {
validateSession.mockClear?.();
validateSession.mockReturnValue({ userId: 'test-user' });
clearAllowlistCache();
vi.spyOn(console, 'log').mockImplementation(vi.fn());
vi.spyOn(console, 'warn').mockImplementation(vi.fn());
vi.spyOn(console, 'error').mockImplementation(vi.fn());
});
describe('CORS preflight', () => {
it('should handle OPTIONS requests properly', async () => {
const res = await request(app)
.options('/')
.query({ url: 'https://example.com' });
expect(res.statusCode).toBe(204);
expect(res.headers['access-control-allow-origin']).toBe('*');
expect(res.headers['access-control-allow-methods']).toBe(
'GET,HEAD,OPTIONS',
);
expect(res.headers['access-control-allow-headers']).toBe(
'Content-Type, X-Actual-Token',
);
expect(res.headers['access-control-max-age']).toBe('600');
});
});
describe('URL parameter validation', () => {
it('should return 400 if url parameter is missing', async () => {
validateSession.mockReturnValue({ userId: 'test-user' });
const res = await request(app).get('/');
expect(res.statusCode).toBe(400);
expect(res.body.error).toBe('Missing url parameter');
});
it('should return 400 if url parameter is invalid', async () => {
validateSession.mockReturnValue({ userId: 'test-user' });
const res = await request(app).get('/').query({ url: 'invalid-url' });
expect(res.statusCode).toBe(400);
expect(res.body.error).toBe('Invalid url parameter');
});
});
describe('Session validation', () => {
it('should return early if validateSession fails', async () => {
validateSession.mockImplementation((req, res) => {
res.status(401).json({ error: 'Unauthorized' });
return null;
});
const res = await request(app)
.get('/')
.query({ url: 'https://example.com' });
expect(res.statusCode).toBe(401);
expect(validateSession).toHaveBeenCalledTimes(1);
});
});
describe('URL allowlist validation', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should block private IP addresses', async () => {
const res = await request(app)
.get('/')
.query({ url: 'http://192.168.1.1/test' });
expect(res.statusCode).toBe(403);
expect(res.body.error).toBe('URL not allowed');
expect(console.warn).toHaveBeenCalledWith(
'Blocked request to private/localhost IP: 192.168.1.1',
);
});
it('should block loopback addresses', async () => {
const res = await request(app)
.get('/')
.query({ url: 'http://127.0.0.1/test' });
expect(res.statusCode).toBe(403);
expect(res.body.error).toBe('URL not allowed');
});
it('should allow allowlisted repository URLs', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(200);
});
it('should allow GitHub API URLs for allowlisted repos', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://api.github.com/repos/user/repo1/releases' });
expect(res.statusCode).toBe(200);
});
it('should allow the exact GitHub API repo URL for allowlisted repos', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://api.github.com/repos/user/repo1' });
expect(res.statusCode).toBe(200);
});
it('should block prefix-matched GitHub API repos that are not allowlisted', async () => {
const res = await request(app).get('/').query({
url: 'https://api.github.com/repos/user/repo1-private/contents/.env',
});
expect(res.statusCode).toBe(403);
expect(res.body.error).toBe('URL not allowed');
expect(console.warn).toHaveBeenCalledWith(
'Blocked request to unauthorized URL',
);
});
it('should allow raw.githubusercontent.com URLs for allowlisted repos', async () => {
const res = await request(app).get('/').query({
url: 'https://raw.githubusercontent.com/user/repo1/main/file.txt',
});
expect(res.statusCode).toBe(200);
});
it('should allow github.com release URLs for allowlisted repos', async () => {
const res = await request(app).get('/').query({
url: 'https://github.com/user/repo1/releases/download/v1.0.0/file.zip',
});
expect(res.statusCode).toBe(200);
});
it.each(['', 'actual:*', 'actual-sensitive:cors-proxy'])(
'keeps rejected URL details behind sensitive debugging (%s)',
async namespaces => {
const previous = createDebug.disable();
createDebug.enable(namespaces);
const log = vi
.spyOn(createDebug, 'log')
.mockImplementation(() => undefined);
const secret = 'private-download-token';
try {
const res = await request(app)
.get('/')
.query({
url: `https://malicious.com/evil?token=${secret}`,
});
expect(res.statusCode).toBe(403);
expect(res.body.error).toBe('URL not allowed');
expect(console.warn).toHaveBeenCalledWith(
'Blocked request to unauthorized URL',
);
expect(JSON.stringify(console.warn.mock.calls)).not.toContain(secret);
const output = log.mock.calls.map(args => format(...args)).join('\n');
expect(output.includes(secret)).toBe(
namespaces === 'actual-sensitive:cors-proxy',
);
} finally {
log.mockRestore();
createDebug.enable(previous);
}
},
);
});
describe('Allowlist fetching and caching', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should fetch allowlist on first request', async () => {
await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1' });
expect(undici.fetch).toHaveBeenCalledWith(
'https://raw.githubusercontent.com/actualbudget/plugin-store/refs/heads/main/plugins.json',
);
});
it('should handle allowlist fetch failure gracefully', async () => {
vi.mocked(undici.fetch).mockImplementation(
createFetchMock({
allowlistFetchFails: true,
proxyResponses: comprehensiveProxyResponses,
}),
);
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(403);
expect(console.error).toHaveBeenCalledWith(
'Failed to fetch plugin allowlist:',
expect.any(Error),
);
vi.mocked(undici.fetch).mockImplementation(
createFetchMock({
proxyResponses: comprehensiveProxyResponses,
}),
);
});
it('should handle allowlist fetch HTTP error', async () => {
vi.mocked(undici.fetch).mockImplementation(
createFetchMock({
allowlistHttpError: true,
proxyResponses: comprehensiveProxyResponses,
}),
);
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(403);
expect(console.error).toHaveBeenCalledWith(
'Failed to fetch plugin allowlist:',
expect.any(Error),
);
vi.mocked(undici.fetch).mockImplementation(
createFetchMock({
proxyResponses: comprehensiveProxyResponses,
}),
);
});
});
describe('HTTP method validation', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should allow GET method', async () => {
const res = await request(app)
.get('/')
.send({ method: 'GET' })
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(200);
});
it('should allow HEAD method', async () => {
const res = await request(app)
.get('/')
.send({ method: 'HEAD' })
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(200);
});
it('should block POST method', async () => {
const res = await request(app)
.get('/')
.send({ method: 'POST' })
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(405);
expect(res.body.error).toBe('Method not allowed');
});
it('should block PUT method', async () => {
const res = await request(app)
.get('/')
.send({ method: 'PUT' })
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(405);
expect(res.body.error).toBe('Method not allowed');
});
it('should reject non-string method (array bypass)', async () => {
undici.fetch.mockClear();
const res = await request(app)
.get('/')
.send({ method: ['POST'], body: { evil: true } })
.query({ url: 'https://api.github.com/repos/user/repo1' });
expect(res.statusCode).toBe(400);
expect(res.body.error).toBe('Invalid method parameter');
const proxyCalls = undici.fetch.mock.calls.filter(
([url]) => url === 'https://api.github.com/repos/user/repo1',
);
expect(proxyCalls).toHaveLength(0);
});
it('should reject non-string method (object bypass)', async () => {
undici.fetch.mockClear();
const res = await request(app)
.get('/')
.send({ method: { toString: () => 'POST' } })
.query({ url: 'https://github.com/user/repo1' });
expect(res.statusCode).toBe(400);
expect(res.body.error).toBe('Invalid method parameter');
const proxyCalls = undici.fetch.mock.calls.filter(
([url]) => url === 'https://github.com/user/repo1',
);
expect(proxyCalls).toHaveLength(0);
});
it('should forward the validated method to fetch, not the raw input', async () => {
undici.fetch.mockClear();
await request(app)
.get('/')
.send({ method: 'get' })
.query({ url: 'https://github.com/user/repo1' });
const proxyCall = undici.fetch.mock.calls.find(
([url]) => url === 'https://github.com/user/repo1',
);
expect(proxyCall).toBeDefined();
expect(proxyCall[1].method).toBe('GET');
});
});
describe('GitHub authentication', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should add GitHub authentication for api.github.com when token is configured', async () => {
config.get.mockReturnValue('test-github-token');
await request(app)
.get('/')
.query({ url: 'https://api.github.com/repos/user/repo1' });
expect(undici.fetch).toHaveBeenCalledWith(
'https://api.github.com/repos/user/repo1',
expect.objectContaining({
headers: expect.objectContaining({
Authorization: 'Bearer test-github-token',
'User-Agent': 'Actual-Budget-Plugin-System',
}),
}),
);
});
it('should add GitHub authentication for raw.githubusercontent.com when token is configured', async () => {
config.get.mockReturnValue('test-github-token');
await request(app).get('/').query({
url: 'https://raw.githubusercontent.com/user/repo1/main/file.txt',
});
expect(undici.fetch).toHaveBeenCalledWith(
'https://raw.githubusercontent.com/user/repo1/main/file.txt',
expect.objectContaining({
headers: expect.objectContaining({
Authorization: 'Bearer test-github-token',
'User-Agent': 'Actual-Budget-Plugin-System',
}),
}),
);
});
it('should not add GitHub authentication when token is not configured', async () => {
config.get.mockReturnValue(null);
await request(app)
.get('/')
.query({ url: 'https://api.github.com/repos/user/repo1' });
expect(undici.fetch).toHaveBeenCalledWith(
'https://api.github.com/repos/user/repo1',
expect.objectContaining({
headers: expect.not.objectContaining({
Authorization: expect.any(String),
}),
}),
);
});
});
describe('Response handling', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should handle JSON responses', async () => {
const jsonData = { name: 'test', version: '1.0.0' };
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/manifest.json' });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('application/json');
expect(res.body).toEqual(jsonData);
});
it('should handle text responses', async () => {
const textContent = 'Hello, world!';
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/readme.txt' });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('text/plain');
expect(res.text).toBe(textContent);
});
it('should handle binary responses', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/file.bin' });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('application/json');
expect(res.body).toEqual({
data: [1, 2, 3, 4, 5],
contentType: 'application/octet-stream',
isBinary: true,
});
});
it('should handle invalid JSON gracefully', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/invalid.json' });
expect(res.statusCode).toBe(200);
expect(res.text).toBe('not valid json');
});
it('should detect JSON from URL patterns', async () => {
const jsonData = { test: true };
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/package.json' });
expect(res.statusCode).toBe(200);
expect(res.headers['content-type']).toContain('application/json');
expect(res.body).toEqual(jsonData);
});
});
describe('Error handling', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should handle fetch errors', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1/network-error' });
expect(res.statusCode).toBe(500);
expect(res.body.error).toBe('Error proxying request');
expect(res.body.details).toBe('Network error');
});
it('should handle invalid repository URLs in allowlist', async () => {
undici.fetch.mockResolvedValueOnce({
ok: true,
json: () => Promise.resolve([{ url: 'invalid-url' }]),
});
const res = await request(app)
.get('/')
.query({ url: 'https://example.com' });
expect(res.statusCode).toBe(403);
expect(console.warn).toHaveBeenCalledWith(
'Blocked request to unauthorized URL',
);
});
});
describe('CORS headers', () => {
beforeEach(() => {
validateSession.mockReturnValue({ userId: 'test-user' });
});
it('should set CORS headers on successful responses', async () => {
const res = await request(app)
.get('/')
.query({ url: 'https://github.com/user/repo1' });
expect(res.headers['access-control-allow-origin']).toBe('*');
});
});
});