A local-first personal finance app
[AI] Support reading secrets from a file with a _FILE environment variable (#8868)
Colin Hebert1dcf7aaa7186
diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 7f74ce3899..540a2408dd 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -41,16 +41,19 @@ Configuration is resolved in this order (highest priority first):### Environment Variables-| Variable | Description |-| ---------------------- | ----------------------------------------------------- |-| `ACTUAL_SERVER_URL` | URL of the Actual sync server (required) |-| `ACTUAL_PASSWORD` | Server password (required unless using token) |-| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password) |-| `ACTUAL_SYNC_ID` | Budget Sync ID (required for most commands) |-| `ACTUAL_DATA_DIR` | Local directory for cached budget data |-| `ACTUAL_CACHE_TTL` | Cache TTL in seconds (default: 60) |-| `ACTUAL_LOCK_TIMEOUT` | Budget-dir lock wait timeout in seconds (default: 10) |-| `ACTUAL_NO_LOCK` | Set to `1` to disable budget-dir locking |+| Variable | Description |+| ---------------------------- | ----------------------------------------------------- |+| `ACTUAL_SERVER_URL` | URL of the Actual sync server (required) |+| `ACTUAL_PASSWORD` | Server password (required unless using token) |+| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password) |+| `ACTUAL_SYNC_ID` | Budget Sync ID (required for most commands) |+| `ACTUAL_DATA_DIR` | Local directory for cached budget data |+| `ACTUAL_CACHE_TTL` | Cache TTL in seconds (default: 60) |+| `ACTUAL_LOCK_TIMEOUT` | Budget-dir lock wait timeout in seconds (default: 10) |+| `ACTUAL_NO_LOCK` | Set to `1` to disable budget-dir locking |+| `ACTUAL_ENCRYPTION_PASSWORD` | Password for end-to-end encrypted budget files |++The three secrets — `ACTUAL_PASSWORD`, `ACTUAL_SESSION_TOKEN` and `ACTUAL_ENCRYPTION_PASSWORD` — can be read from a file instead, by adding `_FILE` to the variable name (for example `ACTUAL_PASSWORD_FILE=/run/secrets/actual-password`). `_FILE`-suffixed environment variables take priority over regular ones.### Config File@@ -83,7 +86,7 @@ Example `.actualrc.json`:}```-**Security:** Avoid storing plaintext passwords in config files (including the `password` key above). If these files do contain passwords, set restrictive permissions (e.g. 600 on Linux), and, if they are in a git repo, add them to `.gitignore`. Prefer environment variables such as `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN`, or use a session token in config instead of a password. See [Environment Variables](#environment-variables) for details.+**Security:** Avoid storing plaintext passwords in config files (including the `password` key above). If these files do contain passwords, set restrictive permissions (e.g. 600 on Linux), and, if they are in a git repo, add them to `.gitignore`. Prefer environment variables such as `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN`, or use a session token in config instead of a password. Better still, use your runtime's built-in support for secrets (e.g. Docker secrets) and point `ACTUAL_PASSWORD_FILE` or `ACTUAL_SESSION_TOKEN_FILE` at the resulting file. See [Environment Variables](#environment-variables) for details.### Global Flagsdiff --git a/packages/cli/src/config.test.ts b/packages/cli/src/config.test.tsindex f0eb7215bf..87bc8ac3b0 100644--- a/packages/cli/src/config.test.ts+++ b/packages/cli/src/config.test.ts@@ -1,4 +1,5 @@-import { homedir } from 'os';+import { mkdtempSync, rmSync, writeFileSync } from 'fs';+import { homedir, tmpdir } from 'os';import { join } from 'path';import { resolveConfig } from './config';@@ -21,7 +22,7 @@ function mockConfigFile(config: Record<string, unknown> | null) {describe('resolveConfig', () => {const savedEnv: Record<string, string | undefined> = {};- const envKeys = [+ const baseEnvKeys = ['ACTUAL_SERVER_URL','ACTUAL_PASSWORD','ACTUAL_SESSION_TOKEN',@@ -32,6 +33,7 @@ describe('resolveConfig', () => {'ACTUAL_LOCK_TIMEOUT','ACTUAL_NO_LOCK',];+ const envKeys = [...baseEnvKeys, ...baseEnvKeys.map(key => `${key}_FILE`)];beforeEach(() => {for (const key of envKeys) {@@ -304,4 +306,104 @@ describe('resolveConfig', () => {expect(config.serverUrl).toBe('http://test');});});++ describe('_FILE environment variables', () => {+ let dir: string;++ const writeSecret = (name: string, contents: string) => {+ const filePath = join(dir, name);+ writeFileSync(filePath, contents);+ return filePath;+ };++ beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'actual-cli-config-'));+ });++ afterEach(() => {+ rmSync(dir, { recursive: true, force: true });+ });++ it('reads a value from the file it points at, trimming whitespace', async () => {+ process.env.ACTUAL_PASSWORD_FILE = writeSecret('password', 'filepw\n');++ const config = await resolveConfig({ serverUrl: 'http://test' });++ expect(config.password).toBe('filepw');+ });++ it('takes precedence over the plain environment variable', async () => {+ process.env.ACTUAL_PASSWORD = 'envpw';+ process.env.ACTUAL_PASSWORD_FILE = writeSecret('password', 'filepw');++ const config = await resolveConfig({ serverUrl: 'http://test' });++ expect(config.password).toBe('filepw');+ });++ it('still loses to a CLI flag', async () => {+ process.env.ACTUAL_PASSWORD_FILE = writeSecret('password', 'filepw');++ const config = await resolveConfig({+ serverUrl: 'http://test',+ password: 'flagpw',+ });++ expect(config.password).toBe('flagpw');+ });++ it('takes precedence over the config file', async () => {+ process.env.ACTUAL_PASSWORD_FILE = writeSecret('password', 'filepw');+ mockConfigFile({ password: 'configpw' });++ const config = await resolveConfig({ serverUrl: 'http://test' });++ expect(config.password).toBe('filepw');+ });++ it('supports the session token and encryption password too', async () => {+ process.env.ACTUAL_SESSION_TOKEN_FILE = writeSecret('token', 'filetok\n');+ process.env.ACTUAL_ENCRYPTION_PASSWORD_FILE = writeSecret(+ 'enc',+ 'fileenc',+ );++ const config = await resolveConfig({ serverUrl: 'http://test' });++ expect(config.sessionToken).toBe('filetok');+ expect(config.encryptionPassword).toBe('fileenc');+ });++ it('is not offered for settings that are not secrets', async () => {+ // Following the Docker secrets convention, only secrets get a _FILE+ // variant. A stray one must be ignored, not silently honoured.+ process.env.ACTUAL_SYNC_ID_FILE = writeSecret('sync', 'from-file');+ process.env.ACTUAL_SYNC_ID = 'from-env';++ const config = await resolveConfig({+ serverUrl: 'http://test',+ password: 'pw',+ });++ expect(config.syncId).toBe('from-env');+ });++ it('throws when the _FILE variable is set but empty', async () => {+ process.env.ACTUAL_PASSWORD = 'envpw';+ process.env.ACTUAL_PASSWORD_FILE = '';++ await expect(resolveConfig({ serverUrl: 'http://test' })).rejects.toThrow(+ 'Could not read ACTUAL_PASSWORD_FILE',+ );+ });++ it('throws when the file cannot be read instead of falling back', async () => {+ process.env.ACTUAL_PASSWORD = 'envpw';+ process.env.ACTUAL_PASSWORD_FILE = join(dir, 'does-not-exist');++ await expect(resolveConfig({ serverUrl: 'http://test' })).rejects.toThrow(+ 'Could not read ACTUAL_PASSWORD_FILE',+ );+ });+ });});diff --git a/packages/cli/src/config.ts b/packages/cli/src/config.tsindex 163c3d7eb8..4d8f80a8c6 100644--- a/packages/cli/src/config.ts+++ b/packages/cli/src/config.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'fs';import { homedir } from 'os';import { join } from 'path';@@ -128,6 +129,25 @@ async function loadConfigFile(): Promise<ConfigFileContent> {return {};}+/**+ * Reads the value of a `<VAR>_FILE` environment variable, returning the+ * contents of the file it points at and throwing if the file is not accessible.+ */+function readFileEnv(fileEnvVar: string): string | undefined {+ const filePath = process.env[fileEnvVar];++ if (filePath === undefined) return undefined;++ try {+ return readFileSync(filePath, 'utf-8').trim();+ } catch (error) {+ const reason = error instanceof Error ? error.message : String(error);+ throw new Error(+ `Could not read ${fileEnvVar} from "${filePath}": ${reason}`,+ );+ }+}+function parseNonNegativeIntEnv(raw: string | undefined,source: string,@@ -156,10 +176,14 @@ export async function resolveConfig('';const password =- cliOpts.password ?? process.env.ACTUAL_PASSWORD ?? fileConfig.password;+ cliOpts.password ??+ readFileEnv('ACTUAL_PASSWORD_FILE') ??+ process.env.ACTUAL_PASSWORD ??+ fileConfig.password;const sessionToken =cliOpts.sessionToken ??+ readFileEnv('ACTUAL_SESSION_TOKEN_FILE') ??process.env.ACTUAL_SESSION_TOKEN ??fileConfig.sessionToken;@@ -174,6 +198,7 @@ export async function resolveConfig(const encryptionPassword =cliOpts.encryptionPassword ??+ readFileEnv('ACTUAL_ENCRYPTION_PASSWORD_FILE') ??process.env.ACTUAL_ENCRYPTION_PASSWORD ??fileConfig.encryptionPassword;diff --git a/packages/docs/docs/api/cli.md b/packages/docs/docs/api/cli.mdindex 82af6fc61d..8e06c2d5fc 100644--- a/packages/docs/docs/api/cli.md+++ b/packages/docs/docs/api/cli.md@@ -30,12 +30,19 @@ The CLI requires a connection to a running Actual sync server. Configuration can### Environment Variables-| Variable | Description |-| ---------------------- | --------------------------------------------------- |-| `ACTUAL_SERVER_URL` | URL of the Actual sync server (required) |-| `ACTUAL_SYNC_ID` | Budget Sync ID (required for most commands) |-| `ACTUAL_PASSWORD` | Server password (one of password or token required) |-| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password) |+| Variable | Description |+| ---------------------------- | ----------------------------------------------------- |+| `ACTUAL_SERVER_URL` | URL of the Actual sync server (required) |+| `ACTUAL_SYNC_ID` | Budget Sync ID (required for most commands) |+| `ACTUAL_PASSWORD` | Server password (one of password or token required) |+| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password) |+| `ACTUAL_DATA_DIR` | Local directory for cached budget data |+| `ACTUAL_CACHE_TTL` | Cache TTL in seconds (default: 60) |+| `ACTUAL_LOCK_TIMEOUT` | Budget-dir lock wait timeout in seconds (default: 10) |+| `ACTUAL_NO_LOCK` | Set to `1` to disable budget-dir locking |+| `ACTUAL_ENCRYPTION_PASSWORD` | Password for end-to-end encrypted budget files |++The three secrets — `ACTUAL_PASSWORD`, `ACTUAL_SESSION_TOKEN` and `ACTUAL_ENCRYPTION_PASSWORD` — can be read from a file instead, by adding `_FILE` to the variable name (for example `ACTUAL_PASSWORD_FILE=/run/secrets/actual-password`). `_FILE`-suffixed environment variables take priority over regular ones.### CLI Flags@@ -83,7 +90,7 @@ Example `.actualrc.json`:```:::caution Security-Avoid storing plaintext passwords in config files (including the `password` key above). If these files do contain passwords, set restrictive permissions (e.g. 600 on Linux), and, if they are in a git repo, add them to `.gitignore`. Prefer environment variables such as `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN`, or use a session token in config instead of a password. See [Environment Variables](#environment-variables) for details.+Avoid storing plaintext passwords in config files (including the `password` key above). If these files do contain passwords, set restrictive permissions (e.g. 600 on Linux), and, if they are in a git repo, add them to `.gitignore`. Prefer environment variables such as `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN`, or use a session token in config instead of a password. Better still, use your runtime's built-in support for secrets (e.g. Docker secrets) and point `ACTUAL_PASSWORD_FILE` or `ACTUAL_SESSION_TOKEN_FILE` at the resulting file. See [Environment Variables](#environment-variables) for details.:::## Usagediff --git a/packages/docs/docs/config/index.md b/packages/docs/docs/config/index.mdindex f9fe287b41..c1e8b46256 100644--- a/packages/docs/docs/config/index.md+++ b/packages/docs/docs/config/index.md@@ -14,6 +14,10 @@ Running into issues with your configuration not being interpreted correctly? Che:::+:::tip+Secrets can be read from a file rather than passed in the environment, which works with Docker secrets and Kubernetes secret volumes. Set `ACTUAL_OPENID_CLIENT_SECRET_FILE` or `ACTUAL_GITHUB_TOKEN_FILE` to the path of a file holding the value. `_FILE`-suffixed environment variables take priority over regular ones. The [CLI](../api/cli.md#environment-variables) supports the same suffix for its own secrets.+:::+## `ACTUAL_DATA_DIR` (config.json: `dataDir`)This is where the server stores the budget data files (and configurations unless `ACTUAL_CONFIG_PATH` is set).diff --git a/packages/docs/docs/config/oauth-auth.md b/packages/docs/docs/config/oauth-auth.mdindex 6b46ae98ad..58887a339e 100644--- a/packages/docs/docs/config/oauth-auth.md+++ b/packages/docs/docs/config/oauth-auth.md@@ -63,6 +63,10 @@ If your OpenId provider does not supports discovery, use the following variables- `ACTUAL_OPENID_CLIENT_SECRET`: client_secret given by the provider- `ACTUAL_OPENID_SERVER_HOSTNAME`: Your Actual Server URL (so the provider redirects you to this)+:::tip+To keep the client secret out of your environment, set `ACTUAL_OPENID_CLIENT_SECRET_FILE` to the path of a file containing it instead. See [Configuring the Server](index.md).+:::+### Configuring OpenID Using the UINavigate into any Budget file, then in the Settings, click on _Start using OpenID_diff --git a/packages/sync-server/src/config-file-env.test.ts b/packages/sync-server/src/config-file-env.test.tsnew file mode 100644index 0000000000..a5288864e8--- /dev/null+++ b/packages/sync-server/src/config-file-env.test.ts@@ -0,0 +1,125 @@+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';++import convict from 'convict';+import { afterEach, beforeEach, describe, expect, it } from 'vitest';++import { applyFileEnv, readFileEnv } from './config-file-env';++describe('config file env', () => {+ let secretDirectory: string;++ const buildSchema = () =>+ convict({+ openId: {+ doc: 'OpenID settings.',+ client_secret: {+ doc: 'Client secret',+ format: String,+ default: '',+ env: 'TEST_SECRET',+ },+ },+ });++ const writeSecret = (name: string, contents: string) => {+ const filePath = join(secretDirectory, name);+ writeFileSync(filePath, contents);+ return filePath;+ };++ beforeEach(() => {+ secretDirectory = mkdtempSync(join(tmpdir(), 'actual-config-file-env-'));+ });++ afterEach(() => {+ rmSync(secretDirectory, { recursive: true, force: true });+ });++ describe('readFileEnv', () => {+ it('reads the contents of the file the variable points at', () => {+ const filePath = writeSecret('secret', 'from-file');++ expect(+ readFileEnv('TEST_SECRET_FILE', { TEST_SECRET_FILE: filePath }),+ ).toBe('from-file');+ });++ it('trims surrounding whitespace from the file value', () => {+ const filePath = writeSecret('secret', ' from-file\n');++ expect(+ readFileEnv('TEST_SECRET_FILE', { TEST_SECRET_FILE: filePath }),+ ).toBe('from-file');+ });++ it('returns undefined when the variable is not set', () => {+ expect(readFileEnv('TEST_SECRET_FILE', {})).toBeUndefined();+ });++ it('throws when the file cannot be read, naming the variable and path', () => {+ const missing = join(secretDirectory, 'does-not-exist');++ expect(() =>+ readFileEnv('TEST_SECRET_FILE', { TEST_SECRET_FILE: missing }),+ ).toThrow(`Could not read TEST_SECRET_FILE from '${missing}'`);+ });++ it('throws when the variable is set but empty', () => {+ // An empty value means a mount that did not produce a path. Falling back+ // to the plain variable here would hide the misconfiguration.+ expect(() =>+ readFileEnv('TEST_SECRET_FILE', { TEST_SECRET_FILE: '' }),+ ).toThrow('Could not read TEST_SECRET_FILE');+ });+ });++ describe('applyFileEnv', () => {+ it('sets the value on the config and reports that it applied', () => {+ const config = buildSchema();+ const filePath = writeSecret('secret', 'from-file');++ const applied = applyFileEnv(+ config,+ 'TEST_SECRET_FILE',+ 'openId.client_secret',+ { TEST_SECRET_FILE: filePath },+ );++ expect(applied).toBe(true);+ expect(config.get('openId.client_secret')).toBe('from-file');+ });++ it('takes precedence over the plain environment variable', () => {+ const config = buildSchema();+ const filePath = writeSecret('secret', 'from-file');++ // convict has already imported TEST_SECRET at this point, exactly as it+ // would at startup.+ config.set('openId.client_secret', 'from-env');++ applyFileEnv(config, 'TEST_SECRET_FILE', 'openId.client_secret', {+ TEST_SECRET: 'from-env',+ TEST_SECRET_FILE: filePath,+ });++ expect(config.get('openId.client_secret')).toBe('from-file');+ });++ it('leaves the setting alone when the variable is not set', () => {+ const config = buildSchema();++ const applied = applyFileEnv(+ config,+ 'TEST_SECRET_FILE',+ 'openId.client_secret',+ {},+ );++ expect(applied).toBe(false);+ expect(config.get('openId.client_secret')).toBe('');+ expect(() => config.validate({ allowed: 'strict' })).not.toThrow();+ });+ });+});diff --git a/packages/sync-server/src/config-file-env.ts b/packages/sync-server/src/config-file-env.tsnew file mode 100644index 0000000000..1ebcb214e0--- /dev/null+++ b/packages/sync-server/src/config-file-env.ts@@ -0,0 +1,47 @@+import fs from 'node:fs';++/** Minimal shape of a convict config; avoids depending on convict's types. */+type ConfigSchema = {+ set(path: string, value: unknown): unknown;+};++/**+ * Reads the value of a `<VAR>_FILE` environment variable, returning the+ * contents of the file it points at and throwing if the file is not accessible.+ */+export function readFileEnv(+ fileEnvVar: string,+ env: NodeJS.ProcessEnv = process.env,+): string | undefined {+ const filePath = env[fileEnvVar];++ if (filePath === undefined) return undefined;++ try {+ return fs.readFileSync(filePath, 'utf8').trim();+ } catch (error) {+ const reason = error instanceof Error ? error.message : String(error);+ throw new Error(+ `Could not read ${fileEnvVar} from '${filePath}': ${reason}`,+ );+ }+}++/**+ * Applies a `<VAR>_FILE` override onto a convict setting, returning whether+ * one was applied.+ */+export function applyFileEnv(+ config: ConfigSchema,+ fileEnvVar: string,+ path: string,+ env: NodeJS.ProcessEnv = process.env,+): boolean {+ const value = readFileEnv(fileEnvVar, env);++ if (value === undefined) return false;++ config.set(path, value);++ return true;+}diff --git a/packages/sync-server/src/load-config-file-env.test.ts b/packages/sync-server/src/load-config-file-env.test.tsnew file mode 100644index 0000000000..3417beaf0b--- /dev/null+++ b/packages/sync-server/src/load-config-file-env.test.ts@@ -0,0 +1,38 @@+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';++import { afterAll, beforeAll, describe, expect, it } from 'vitest';++import type { config as loadedConfig } from './load-config';++// load-config reads the environment when it is first imported, so the+// environment has to be set up before importing it.+describe('load-config _FILE overrides', () => {+ let secretDirectory: string;+ let config: typeof loadedConfig;++ beforeAll(async () => {+ secretDirectory = mkdtempSync(join(tmpdir(), 'actual-load-config-'));++ const secretPath = join(secretDirectory, 'client-secret');+ writeFileSync(secretPath, 'secret-from-file\n');++ process.env.ACTUAL_OPENID_CLIENT_SECRET_FILE = secretPath;+ // Also set the plain variable, which convict imports at construction time+ // and re-imports at the end of loadFile. The file must still win.+ process.env.ACTUAL_OPENID_CLIENT_SECRET = 'secret-from-env';++ ({ config } = await import('./load-config'));+ });++ afterAll(() => {+ delete process.env.ACTUAL_OPENID_CLIENT_SECRET_FILE;+ delete process.env.ACTUAL_OPENID_CLIENT_SECRET;+ rmSync(secretDirectory, { recursive: true, force: true });+ });++ it('loads the secret from the file, superseding the plain variable', () => {+ expect(config.get('openId.client_secret')).toBe('secret-from-file');+ });+});diff --git a/packages/sync-server/src/load-config.js b/packages/sync-server/src/load-config.jsindex 5ddf78437d..0cf24df1ae 100644--- a/packages/sync-server/src/load-config.js+++ b/packages/sync-server/src/load-config.js@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';import convict from 'convict';import createDebug from 'debug';+import { applyFileEnv } from './config-file-env';+const require = createRequire(import.meta.url);const debug = createDebug('actual:config');const debugSensitive = createDebug('actual-sensitive:config');@@ -320,6 +322,17 @@ if (fs.existsSync(configPath)) {debug(`Config loaded`);}+// `<VAR>_FILE` is applied after loadFile so it beats both config.json and the+// plain environment variable, and before validate so the value is checked.+for (const [fileEnvVar, settingPath] of [+ ['ACTUAL_OPENID_CLIENT_SECRET_FILE', 'openId.client_secret'],+ ['ACTUAL_GITHUB_TOKEN_FILE', 'github.token'],+]) {+ if (applyFileEnv(configSchema, fileEnvVar, settingPath)) {+ debug(`Loaded ${settingPath} from ${fileEnvVar}`);+ }+}+debug(`Validating config`);configSchema.validate({ allowed: 'strict' });diff --git a/upcoming-release-notes/support-file-mounted-secrets.md b/upcoming-release-notes/support-file-mounted-secrets.mdnew file mode 100644index 0000000000..e12b286296--- /dev/null+++ b/upcoming-release-notes/support-file-mounted-secrets.md@@ -0,0 +1,6 @@+---+category: Enhancements+authors: [ColinHebert]+---++Secrets can now be read from a file instead of being passed in an environment variable