Skip to content

A local-first personal finance app

17.3 KB
Raw Blame
import createDebug from 'debug';
import type { Request, Response } from 'express';
import express from 'express';
import { v4 as uuidv4 } from 'uuid';

import { isAdmin } from '#account-db';
import { handleError } from '#app-gocardless/util/handle-error';
import { SecretName, secretsService } from '#services/secrets-service';
import {
  requestLoggerMiddleware,
  validateSessionMiddleware,
} from '#util/middlewares';
import { isBlockedIp } from '#util/ssrf';

import type {
  EnableBankingSession,
  PsuHeaders,
} from './services/enablebanking-service';
import {
  enableBankingService,
  isImportableTransaction,
  normalizeAccount,
  normalizeBalance,
  normalizeTransaction,
} from './services/enablebanking-service';
import { EnableBankingError } from './utils/errors';

const debugSensitive = createDebug('actual-sensitive:enable-banking');

const debug = createDebug('actual:enable-banking:app');

const app = express();
export { app as handlers };
app.use(requestLoggerMiddleware);
app.use(express.json());

// --- Shared helpers ---

function extractPsuHeaders(req: Request): PsuHeaders {
  const ip = req.ip;
  const ua =
    typeof req.headers['user-agent'] === 'string'
      ? req.headers['user-agent']
      : undefined;

  if (!ip || isBlockedIp(ip)) {
    debug('Skipping PSU headers because PSU IP is local/private');
    return {};
  }

  const headers: PsuHeaders = {
    'Psu-Ip-Address': ip,
  };

  if (ua) {
    headers['Psu-User-Agent'] = ua;
  }

  debug('Using PSU headers for public PSU IP');

  return headers;
}

// Some ASPSPs reject PSU headers on balance/transaction data-access calls even
// though they require them during the authorization step. List their names here.
const ASPSPS_WITHOUT_DATA_ACCESS_PSU_HEADERS = new Set(['HypoVereinsbank']);

function dataAccessPsuHeaders(
  aspspName: string | undefined,
  psuHeaders: PsuHeaders | undefined,
): PsuHeaders | undefined {
  if (aspspName && ASPSPS_WITHOUT_DATA_ACCESS_PSU_HEADERS.has(aspspName)) {
    return undefined;
  }
  return psuHeaders;
}

async function buildSessionResult(
  session: EnableBankingSession,
  psuHeaders?: PsuHeaders,
) {
  const accessHeaders = dataAccessPsuHeaders(session.aspsp?.name, psuHeaders);
  const accountsWithBalances = await Promise.all(
    session.accounts.map(async account => {
      const normalized = normalizeAccount(account, session.aspsp);

      let balances: ReturnType<typeof normalizeBalance>[] = [];
      try {
        const balanceResult = await enableBankingService.getBalances(
          account.uid,
          accessHeaders,
        );
        balances = balanceResult.balances.map(normalizeBalance);
      } catch (err) {
        debug('Failed to fetch account balances');
        debugSensitive(
          'Failed to fetch balances for account %s: %O',
          account.uid,
          err,
        );
      }

      const preferredBalance =
        balances.find(b => b.balanceType === 'CLAV') ?? balances[0];

      return {
        ...normalized,
        balance: preferredBalance ? preferredBalance.balanceAmount.amount : 0,
        balances,
      };
    }),
  );

  return {
    session_id: session.session_id,
    accounts: accountsWithBalances,
    aspsp: session.aspsp,
  };
}

// Auth callback from bank redirect — must be before validateSessionMiddleware
// since the bank redirects here directly (no auth token available)
app.get('/auth_callback', async (req: Request, res: Response) => {
  const code = typeof req.query.code === 'string' ? req.query.code : undefined;
  const state =
    typeof req.query.state === 'string' ? req.query.state : undefined;

  if (!code) {
    res
      .status(400)
      .send(
        '<html><body><p>Authorization failed: missing code.</p></body></html>',
      );
    return;
  }

  if (!state) {
    res
      .status(400)
      .send(
        '<html><body><p>Authorization failed: missing state parameter.</p></body></html>',
      );
    return;
  }

  try {
    const session = await enableBankingService.createSession(code);
    debug('Callback session created with %d accounts', session.accounts.length);
    debugSensitive('Callback session created: %s', session.session_id);

    const result = await buildSessionResult(session, extractPsuHeaders(req));

    // Always cache the result so retries within TTL can read it
    completedAuths.set(state, result);
    setTimeout(() => completedAuths.delete(state), COMPLETED_AUTH_TTL_MS);

    const pending = pendingAuths.get(state);
    if (pending) {
      pending.resolve(result);
      cleanupPendingAuth(state);
    }

    res.send(
      '<html><body><p>Authorization successful. This window will close.</p>' +
        '<script>setTimeout(function(){window.close()},1000)</script></body></html>',
    );
  } catch (error) {
    const errorResult = {
      error: error instanceof Error ? error.message : 'unknown error',
    };

    completedAuths.set(state, errorResult);
    setTimeout(() => completedAuths.delete(state), COMPLETED_AUTH_TTL_MS);

    const pending = pendingAuths.get(state);
    if (pending) {
      pending.reject(error);
      cleanupPendingAuth(state);
    }

    debug('Callback authentication failed');
    debugSensitive('Callback authentication failed: %O', error);
    res
      .status(500)
      .send(
        '<html><body><p>Authorization failed. You can close this window and try again.</p></body></html>',
      );
  }
});

app.use(validateSessionMiddleware);

// --- Poll/complete-auth coordination ---

type PendingAuth = {
  id: string;
  resolve: (value: unknown) => void;
  reject: (reason: unknown) => void;
  timer: ReturnType<typeof setTimeout>;
};

// NOTE: These in-memory maps make the auth handoff process-local.
// Multi-instance deployments require sticky routing so the same instance
// handles both the callback and client poll for a given state.
const pendingAuths = new Map<string, PendingAuth>();
const completedAuths = new Map<string, unknown>();
let nextWaiterId = 0;

const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
const COMPLETED_AUTH_TTL_MS = 30 * 1000; // 30 seconds

function cleanupPendingAuth(state: string, waiterId?: string) {
  const entry = pendingAuths.get(state);
  if (entry && (waiterId == null || entry.id === waiterId)) {
    clearTimeout(entry.timer);
    pendingAuths.delete(state);
  }
}

// --- Routes ---

app.post(
  '/status',
  handleError(async (req: Request, res: Response) => {
    const configured = enableBankingService.isConfigured();

    res.send({
      status: 'ok',
      data: {
        configured,
      },
    });
  }),
);

app.post(
  '/configure',
  handleError(async (req: Request, res: Response) => {
    if (!isAdmin(res.locals.user_id)) {
      res.status(403).send({
        status: 'error',
        reason: 'forbidden',
        details: 'permission-not-found',
      });
      return;
    }

    const { applicationId, secretKey } = req.body || {};

    if (!applicationId || !secretKey) {
      res.send({
        status: 'ok',
        data: {
          error_code: 'INVALID_INPUT',
          error_type: 'Missing applicationId or secretKey',
        },
      });
      return;
    }

    // Validate credentials before persisting to avoid exposing
    // transient bad creds to concurrent requests
    try {
      const appInfo = await enableBankingService.validateCredentials(
        applicationId,
        secretKey,
      );
      debug('Enable Banking application validated');
      debugSensitive('Enable Banking application validated: %O', appInfo);
    } catch (error) {
      debug('Enable Banking configuration validation failed');
      debugSensitive(
        'Enable Banking configuration validation failed: %O',
        error,
      );
      res.send({
        status: 'ok',
        data: {
          error_code: 'CONFIGURATION_FAILED',
          error_type: error instanceof Error ? error.message : 'unknown error',
        },
      });
      return;
    }

    // Only persist after successful validation
    secretsService.set(SecretName.enablebanking_applicationId, applicationId);
    secretsService.set(SecretName.enablebanking_secretKey, secretKey);

    res.send({
      status: 'ok',
      data: {
        configured: true,
      },
    });
  }),
);

app.post(
  '/aspsps',
  handleError(async (req: Request, res: Response) => {
    const { country } = req.body || {};

    try {
      const aspsps = await enableBankingService.getAspsps(country);

      res.send({
        status: 'ok',
        data: aspsps,
      });
    } catch (error) {
      res.send({
        status: 'ok',
        data: {
          error: error instanceof Error ? error.message : 'unknown error',
        },
      });
    }
  }),
);

app.post(
  '/start-auth',
  handleError(async (req: Request, res: Response) => {
    const { aspsp, redirectUrl, maxConsentValidity, psuType } = req.body || {};

    if (!aspsp || !redirectUrl) {
      res.send({
        status: 'ok',
        data: {
          error_code: 'INVALID_INPUT',
          error_type: 'Missing aspsp or redirectUrl',
        },
      });
      return;
    }

    const state = uuidv4();

    try {
      const authResponse = await enableBankingService.startAuth(
        aspsp,
        redirectUrl,
        state,
        typeof maxConsentValidity === 'number' ? maxConsentValidity : undefined,
        psuType === 'business' ? 'business' : 'personal',
        extractPsuHeaders(req),
      );

      res.send({
        status: 'ok',
        data: {
          url: authResponse.url,
          state,
        },
      });
    } catch (error) {
      res.send({
        status: 'ok',
        data: {
          error: error instanceof Error ? error.message : 'unknown error',
        },
      });
    }
  }),
);

app.post(
  '/complete-auth',
  handleError(async (req: Request, res: Response) => {
    const { code, state } = req.body || {};

    if (!code) {
      res.send({
        status: 'ok',
        data: {
          error_code: 'INVALID_INPUT',
          error_type: 'Missing code',
        },
      });
      return;
    }

    try {
      const session = await enableBankingService.createSession(code);
      debug('Session created with %d accounts', session.accounts.length);
      debugSensitive('Session created: %s', session.session_id);

      const result = await buildSessionResult(session, extractPsuHeaders(req));

      // Always cache so retries within TTL can read the result
      if (state) {
        completedAuths.set(state, result);
        setTimeout(() => completedAuths.delete(state), COMPLETED_AUTH_TTL_MS);

        const pending = pendingAuths.get(state);
        if (pending) {
          pending.resolve(result);
          cleanupPendingAuth(state);
        }
      }

      res.send({
        status: 'ok',
        data: result,
      });
    } catch (error) {
      const errorResult = {
        error: error instanceof Error ? error.message : 'unknown error',
      };

      if (state) {
        completedAuths.set(state, errorResult);
        setTimeout(() => completedAuths.delete(state), COMPLETED_AUTH_TTL_MS);

        const pending = pendingAuths.get(state);
        if (pending) {
          pending.reject(error);
          cleanupPendingAuth(state);
        }
      }

      res.send({
        status: 'ok',
        data: errorResult,
      });
    }
  }),
);

app.post(
  '/poll-auth',
  handleError(async (req: Request, res: Response) => {
    const { state } = req.body || {};

    if (!state) {
      res.send({
        status: 'ok',
        data: {
          error_code: 'INVALID_INPUT',
          error_type: 'Missing state',
        },
      });
      return;
    }

    const waiterId = String(++nextWaiterId);
    let hasClientDisconnected = false;

    try {
      // If complete-auth already fired before poll-auth, return immediately
      if (completedAuths.has(state)) {
        const result = completedAuths.get(state);
        completedAuths.delete(state);
        res.send({ status: 'ok', data: result });
        return;
      }

      const result = await new Promise((resolve, reject) => {
        // Clean up any existing waiter for this state
        const existing = pendingAuths.get(state);
        if (existing) {
          clearTimeout(existing.timer);
          existing.reject(new Error('Poll superseded'));
        }

        let settled = false;
        const safeResolve = (value: unknown) => {
          if (settled) return;
          settled = true;
          resolve(value);
        };
        const safeReject = (reason: unknown) => {
          if (settled) return;
          settled = true;
          reject(reason);
        };

        const timer = setTimeout(() => {
          cleanupPendingAuth(state, waiterId);
          safeReject(new Error('Polling timed out'));
        }, POLL_TIMEOUT_MS);

        pendingAuths.set(state, {
          id: waiterId,
          resolve: safeResolve,
          reject: safeReject,
          timer,
        });

        // Clean up if client disconnects before resolution
        res.on('close', () => {
          if (!res.writableFinished && !settled) {
            hasClientDisconnected = true;
            cleanupPendingAuth(state, waiterId);
            safeReject(new Error('Client disconnected'));
          }
        });
      });

      if (hasClientDisconnected || res.destroyed || res.writableEnded) {
        return;
      }

      res.send({
        status: 'ok',
        data: result,
      });
    } catch (error) {
      cleanupPendingAuth(state, waiterId);
      if (hasClientDisconnected || res.destroyed || res.writableEnded) {
        return;
      }
      res.send({
        status: 'ok',
        data: {
          error: error instanceof Error ? error.message : 'unknown error',
        },
      });
    }
  }),
);

app.post(
  '/transactions',
  handleError(async (req: Request, res: Response) => {
    const { accountId, startDate, aspspName } = req.body || {};

    if (!accountId || !startDate) {
      res.send({
        status: 'ok',
        data: {
          error_code: 'INVALID_INPUT',
          error_type: 'Missing accountId or startDate',
        },
      });
      return;
    }

    try {
      const dateTo = new Date().toISOString().split('T')[0];
      const dateFrom =
        typeof startDate === 'string'
          ? startDate
          : new Date(startDate).toISOString().split('T')[0];

      const psuHeaders = dataAccessPsuHeaders(
        aspspName,
        extractPsuHeaders(req),
      );

      // Fetch balances
      const balanceResult = await enableBankingService.getBalances(
        accountId,
        psuHeaders,
      );
      const balances = balanceResult.balances.map(normalizeBalance);

      // Determine starting balance, preferring CLAV balance type
      let startingBalance = 0;
      if (balances.length > 0) {
        const preferredBalance =
          balances.find(b => b.balanceType === 'CLAV') ?? balances[0];
        startingBalance = preferredBalance.balanceAmount.amount;
      }

      // Fetch all paginated transactions
      const rawTransactions = await enableBankingService.getAllTransactions(
        accountId,
        dateFrom,
        dateTo,
        psuHeaders,
      );

      const all: ReturnType<typeof normalizeTransaction>[] = [];
      const booked: ReturnType<typeof normalizeTransaction>[] = [];
      const pending: ReturnType<typeof normalizeTransaction>[] = [];

      for (const tx of rawTransactions) {
        const normalized = normalizeTransaction(tx);

        // Drop records Actual's client can't insert (empty/non-ISO date or
        // non-numeric amount) — one of them would otherwise abort the entire
        // account sync. Pending transactions that carry a date are unaffected.
        if (!isImportableTransaction(normalized)) {
          debugSensitive(
            'Skipping unimportable transaction id=%s date=%s amount=%s',
            normalized.transactionId,
            normalized.date,
            normalized.transactionAmount.amount,
          );
          continue;
        }

        all.push(normalized);
        if (normalized.booked) {
          booked.push(normalized);
        } else {
          pending.push(normalized);
        }
      }

      res.send({
        status: 'ok',
        data: {
          transactions: {
            all,
            booked,
            pending,
          },
          balances,
          startingBalance,
        },
      });
    } catch (error) {
      debug('Error fetching transactions');
      debugSensitive('Error fetching transactions: %O', error);

      // Return structured error codes so the client can show
      // appropriate UI (e.g. re-auth prompt for expired sessions)
      if (error instanceof EnableBankingError) {
        if (error.error_code === 'INVALID_ACCESS_TOKEN') {
          res.send({
            status: 'ok',
            data: {
              error_type: 'ITEM_ERROR',
              error_code: 'ITEM_LOGIN_REQUIRED',
            },
          });
          return;
        }

        // The bank-sync wire format expects `error_type` to be a broad
        // machine-readable category (matched by AccountSyncCheck's switch),
        // not the human message we now keep on `EnableBankingError.error_type`.
        const wireErrorType =
          error.error_code === 'NOT_FOUND' ? 'INVALID_INPUT' : error.error_code;

        res.send({
          status: 'ok',
          data: {
            error_type: wireErrorType,
            error_code: error.error_code,
          },
        });
        return;
      }

      res.send({
        status: 'ok',
        data: {
          error_type: 'INTERNAL_ERROR',
          error_code: 'INTERNAL_ERROR',
        },
      });
    }
  }),
);