A local-first personal finance app
import createDebug from 'debug';
import express from 'express';
import { fetch } from 'undici';
import { handleError } from '#app-gocardless/util/handle-error';
import { config } from '#load-config';
import { SecretName, secretsService } from '#services/secrets-service';
import * as UserService from '#services/user-service';
import {
requestLoggerMiddleware,
validateSessionMiddleware,
} from '#util/middlewares';
import { isValidFileId } from '#util/paths';
import { assertUrlAllowed, createSsrfDispatcher } from '#util/ssrf';
const debugSensitive = createDebug('actual-sensitive:simplefin');
const networkOptions = {
allowedNetworks: config.get('simplefinAllowedNetworks'),
};
const dispatcher = createSsrfDispatcher(networkOptions);
const app = express();
export { app as handlers };
app.use(requestLoggerMiddleware);
app.use(express.json());
app.use(validateSessionMiddleware);
app.use((req, res, next) => {
const fileId = req.get('X-Actual-File-Id');
if (fileId != null) {
if (!isValidFileId(fileId)) {
res.status(400).send({ status: 'error', reason: 'invalid-file-id' });
return;
}
if (!UserService.canAccessActiveFile(fileId, res.locals.user_id)) {
res.status(403).send({ status: 'error', reason: 'file-access-denied' });
return;
}
}
// Select the pair together, even if a budget's setup token is invalid.
// Falling back in that case could expose global accounts unexpectedly.
res.locals.credentialFileId =
fileId != null &&
(secretsService.exists(SecretName.simplefin_token, fileId) ||
secretsService.exists(SecretName.simplefin_accessKey, fileId))
? fileId
: null;
next();
});
app.post(
'/status',
handleError(async (req, res) => {
const token = secretsService.get(
SecretName.simplefin_token,
res.locals.credentialFileId,
);
const configured = token != null && !isForbidden(token);
res.send({
status: 'ok',
data: {
configured,
source: res.locals.credentialFileId
? 'per-budget-file'
: configured
? 'global'
: null,
},
});
}),
);
app.post(
'/accounts',
handleError(async (req, res) => {
let accessKey = secretsService.get(
SecretName.simplefin_accessKey,
res.locals.credentialFileId,
);
if (isInvalidAccessKey(accessKey)) {
const token = secretsService.get(
SecretName.simplefin_token,
res.locals.credentialFileId,
);
if (token == null || isForbidden(token)) {
invalidToken(res);
return;
}
const claimUrl = decodeClaimUrl(token);
if (claimUrl == null) {
console.log(
'SimpleFIN setup token does not decode to a claim URL - re-enter the token',
);
invalidToken(res);
return;
}
try {
accessKey = await claimAccessKey(claimUrl);
} catch (e) {
console.log('Failed to claim the SimpleFIN setup token:');
serverDown(e, res);
return;
}
if (isInvalidAccessKey(accessKey)) {
console.log('SimpleFIN rejected the setup token claim');
debugSensitive(
'SimpleFIN rejected the setup token claim: %s',
accessKey.slice(0, 200) || '(empty response)',
);
invalidToken(res);
return;
}
secretsService.set(
SecretName.simplefin_accessKey,
accessKey,
res.locals.credentialFileId,
);
}
try {
const accounts = await getAccounts(accessKey, null, null, null, true);
res.send({
status: 'ok',
data: {
accounts: accounts.accounts,
},
});
} catch (e) {
serverDown(e, res);
return;
}
}),
);
app.post(
'/transactions',
handleError(async (req, res) => {
const { accountId, startDate } = req.body || {};
const accessKey = secretsService.get(
SecretName.simplefin_accessKey,
res.locals.credentialFileId,
);
if (isInvalidAccessKey(accessKey)) {
invalidToken(res);
return;
}
if (Array.isArray(accountId) !== Array.isArray(startDate)) {
console.log({ accountId, startDate });
throw new Error(
'accountId and startDate must either both be arrays or both be strings',
);
}
if (Array.isArray(accountId) && accountId.length !== startDate.length) {
console.log({ accountId, startDate });
throw new Error('accountId and startDate arrays must be the same length');
}
const earliestStartDate = Array.isArray(startDate)
? startDate.reduce((a, b) => (a < b ? a : b))
: startDate;
let results;
try {
results = await getTransactions(
accessKey,
Array.isArray(accountId) ? accountId : [accountId],
new Date(earliestStartDate),
);
} catch (e) {
if (isForbidden(e.message)) {
invalidToken(res);
} else {
serverDown(e, res);
}
return;
}
let response = {};
if (Array.isArray(accountId)) {
for (let i = 0; i < accountId.length; i++) {
const id = accountId[i];
response[id] = getAccountResponse(results, id, new Date(startDate[i]));
}
} else {
response = getAccountResponse(results, accountId, new Date(startDate));
}
if (results.hasError) {
res.send({
status: 'ok',
data: !Array.isArray(accountId)
? results.errors[accountId][0]
: {
...response,
errors: results.errors,
},
});
return;
}
res.send({
status: 'ok',
data: response,
});
}),
);
function logAccountError(results, accountId, data) {
const errors = results.errors[accountId] || [];
errors.push(data);
results.errors[accountId] = errors;
results.hasError = true;
}
function getAccountResponse(results, accountId, startDate) {
const account =
!results?.accounts || results.accounts.find(a => a.id === accountId);
if (!account) {
console.log(
`The account "${accountId}" was not found. Here were the accounts returned:`,
);
if (results?.accounts) {
results.accounts.forEach(a => console.log(`${a.id} - ${a.org.name}`));
}
logAccountError(results, accountId, {
error_type: 'ACCOUNT_MISSING',
error_code: 'ACCOUNT_MISSING',
reason: `The account "${accountId}" was not found. Try unlinking and relinking the account.`,
});
return;
}
const needsAttention = results.sferrors.find(e =>
e.startsWith(`Connection to ${account.org.name} may need attention`),
);
if (needsAttention) {
logAccountError(results, accountId, {
error_type: 'ACCOUNT_NEEDS_ATTENTION',
error_code: 'ACCOUNT_NEEDS_ATTENTION',
reason:
'The account needs your attention at <a href="https://bridge.simplefin.org/auth/login">SimpleFIN</a>.',
});
}
const startingBalance = parseInt(account.balance.replace('.', ''));
const date = getDate(new Date(account['balance-date'] * 1000));
const balances = [
{
balanceAmount: {
amount: account.balance,
currency: account.currency,
},
balanceType: 'expected',
referenceDate: date,
},
{
balanceAmount: {
amount: account.balance,
currency: account.currency,
},
balanceType: 'interimAvailable',
referenceDate: date,
},
];
const all = [];
const booked = [];
const pending = [];
for (const trans of account.transactions) {
const newTrans = {};
let dateToUse = 0;
if (trans.pending ?? trans.posted === 0) {
newTrans.booked = false;
dateToUse = trans.transacted_at;
} else {
newTrans.booked = true;
dateToUse = trans.posted;
}
const transactionDate = new Date(dateToUse * 1000);
if (transactionDate < startDate) {
continue;
}
newTrans.sortOrder = dateToUse;
newTrans.date = getDate(transactionDate);
newTrans.payeeName = trans.payee;
newTrans.notes = trans.description;
newTrans.transactionAmount = { amount: trans.amount, currency: 'USD' };
newTrans.transactionId = trans.id;
newTrans.valueDate = newTrans.bookingDate;
if (trans.transacted_at) {
newTrans.transactedDate = getDate(new Date(trans.transacted_at * 1000));
}
if (trans.posted) {
newTrans.postedDate = getDate(new Date(trans.posted * 1000));
}
if (newTrans.booked) {
booked.push(newTrans);
} else {
pending.push(newTrans);
}
all.push(newTrans);
}
const sortFunction = (a, b) => b.sortOrder - a.sortOrder;
const bookedSorted = booked.sort(sortFunction);
const pendingSorted = pending.sort(sortFunction);
const allSorted = all.sort(sortFunction);
return {
balances,
startingBalance,
transactions: {
all: allSorted,
booked: bookedSorted,
pending: pendingSorted,
},
};
}
function invalidToken(res) {
res.send({
status: 'ok',
data: {
error_type: 'INVALID_ACCESS_TOKEN',
error_code: 'INVALID_ACCESS_TOKEN',
status: 'rejected',
reason:
'Invalid SimpleFIN access token. Reset the token and re-link any broken accounts.',
},
});
}
function serverDown(e, res) {
console.log('Error communicating with SimpleFIN');
debugSensitive('Error communicating with SimpleFIN: %O', e);
res.send({
status: 'ok',
data: {
error_type: 'SERVER_DOWN',
error_code: 'SERVER_DOWN',
status: 'rejected',
reason: 'There was an error communicating with SimpleFIN.',
},
});
}
const ACCESS_KEY_FORMAT = /^.*\/\/.*:.*@.*$/;
function parseAccessKey(accessKey) {
let scheme = null;
let rest = null;
let auth = null;
let username = null;
let password = null;
let baseUrl = null;
if (!accessKey || !ACCESS_KEY_FORMAT.test(accessKey)) {
console.log('Invalid SimpleFIN access key');
throw new Error(`Invalid access key`);
}
[scheme, rest] = accessKey.split('//');
[auth, rest] = rest.split('@');
[username, password] = auth.split(':');
baseUrl = `${scheme}//${rest}`;
return {
baseUrl,
username,
password,
};
}
function decodeClaimUrl(base64Token) {
const decoded = Buffer.from(base64Token, 'base64').toString();
let url;
try {
url = new URL(decoded);
} catch {
return null;
}
if (url.protocol !== 'https:' && url.protocol !== 'http:') {
return null;
}
return decoded;
}
async function claimAccessKey(claimUrl) {
await assertUrlAllowed(claimUrl, networkOptions);
// don't auto-follow redirects for SSRF safety
const response = await fetch(claimUrl, {
method: 'POST',
redirect: 'manual',
dispatcher,
});
if (!response.ok && response.status !== 403) {
throw new Error(`SimpleFIN claim failed with HTTP ${response.status}`);
}
return (await response.text()).trim();
}
function isForbidden(value) {
return typeof value === 'string' && value.startsWith('Forbidden');
}
function isInvalidAccessKey(accessKey) {
return (
typeof accessKey !== 'string' ||
isForbidden(accessKey) ||
!ACCESS_KEY_FORMAT.test(accessKey)
);
}
async function getTransactions(accessKey, accounts, startDate, endDate) {
const now = new Date();
startDate = startDate || new Date(now.getFullYear(), now.getMonth(), 1);
endDate = endDate || new Date(now.getFullYear(), now.getMonth() + 1, 1);
console.log(`${getDate(startDate)} - ${getDate(endDate)}`);
return await getAccounts(accessKey, accounts, startDate, endDate);
}
function getDate(date) {
return date.toISOString().split('T')[0];
}
function normalizeDate(date) {
return (date.valueOf() - date.getTimezoneOffset() * 60 * 1000) / 1000;
}
async function getAccounts(
accessKey,
accounts,
startDate,
endDate,
noTransactions = false,
) {
const sfin = parseAccessKey(accessKey);
const headers = {
Authorization: `Basic ${Buffer.from(
`${sfin.username}:${sfin.password}`,
).toString('base64')}`,
};
const params = new URLSearchParams();
if (!noTransactions) {
if (startDate) {
params.append('start-date', normalizeDate(startDate));
}
if (endDate) {
params.append('end-date', normalizeDate(endDate));
}
params.append('pending', '1');
} else {
params.append('balances-only', '1');
}
if (accounts) {
for (const id of accounts) {
params.append('account', id);
}
}
const url = new URL(`${sfin.baseUrl}/accounts`);
url.search = params.toString();
// Follow redirects manually so every hop is re-validated against the SSRF
// rules; fetch's automatic 'follow' would let a 3xx response redirect to a
// blocked address after only the initial URL was checked. Authorization is
// dropped once a redirect leaves the original origin (matching fetch's
// default cross-origin stripping) so the bridge credentials aren't leaked.
const MAX_REDIRECTS = 5;
let currentUrl = url.toString();
let response;
for (let hop = 0; ; hop++) {
await assertUrlAllowed(currentUrl, networkOptions);
response = await fetch(currentUrl, {
method: 'GET',
headers,
redirect: 'manual',
dispatcher,
});
const location = response.headers.get('location');
if (response.status < 300 || response.status >= 400 || !location) {
break;
}
if (hop >= MAX_REDIRECTS) {
throw new Error('Too many redirects');
}
const nextUrl = new URL(location, currentUrl);
if (nextUrl.origin !== new URL(currentUrl).origin) {
delete headers.Authorization;
}
currentUrl = nextUrl.toString();
}
if (response.status === 403) {
throw new Error('Forbidden');
}
const text = await response.text();
try {
const results = JSON.parse(text);
results.sferrors = results.errors;
results.hasError = false;
results.errors = {};
return results;
} catch (e) {
console.log('Error parsing SimpleFIN response');
debugSensitive('Error parsing SimpleFIN response: %s', text);
throw e;
}
}