@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/config/resolvers/prompt.js

@@ -0,0 +1,159 @@
+import { randomInt } from 'node:crypto';
+import { ResolveError } from './types.js';
+/** The value needs asking for, and nobody can be asked (and no earlier answer is remembered). */
+export class PromptRequiredError extends ResolveError {
+    name = 'PromptRequiredError';
+    constructor(envName, field) {
+        super(envName, field, 'needs a prompt; not available non-interactively');
+    }
+}
+const maskedFields = new Set(['password', 'tls.keyPassphrase']);
+// Short, common and unlike each other, so they are quick to read and type.
+const words = [
+    'apple',
+    'arrow',
+    'badge',
+    'basin',
+    'beach',
+    'bench',
+    'berry',
+    'bison',
+    'blade',
+    'bloom',
+    'brick',
+    'bridge',
+    'cabin',
+    'candle',
+    'canyon',
+    'cedar',
+    'cliff',
+    'cloud',
+    'clover',
+    'comet',
+    'coral',
+    'crane',
+    'daisy',
+    'delta',
+    'ember',
+    'falcon',
+    'fern',
+    'field',
+    'flint',
+    'forest',
+    'garden',
+    'glacier',
+    'harbor',
+    'hazel',
+    'island',
+    'jungle',
+    'kettle',
+    'lantern',
+    'lemon',
+    'maple',
+    'meadow',
+    'mirror',
+    'novel',
+    'olive',
+    'orchid',
+    'otter',
+    'pebble',
+    'pepper',
+    'planet',
+    'pocket',
+    'quartz',
+    'rabbit',
+    'river',
+    'saddle',
+    'silver',
+    'spruce',
+    'summit',
+    'ticket',
+    'timber',
+    'velvet',
+    'willow',
+    'window',
+    'yellow',
+    'zebra',
+];
+const CONFIRM_ATTEMPTS = 3;
+const challengeWords = () => {
+    const first = randomInt(words.length);
+    let second = randomInt(words.length - 1);
+    if (second >= first)
+        second += 1;
+    return `${words[first]} ${words[second]}`;
+};
+const sameWords = (typed, expected) => typed.trim().split(/\s+/).join(' ').toLowerCase() === expected;
+const keyOf = (envName, field) => `${envName}\0${field}`;
+// Answers are kept in memory for the rest of the process, so a field is asked for once.
+export function createPromptResolver(prompter) {
+    const answers = new Map();
+    const confirmed = new Map();
+    return {
+        kind: 'prompt',
+        resolve(_ref, ctx) {
+            const key = keyOf(ctx.envName, ctx.field);
+            const remembered = answers.get(key);
+            if (remembered)
+                return remembered;
+            if (!ctx.interactive)
+                return Promise.reject(new PromptRequiredError(ctx.envName, ctx.field));
+            const answer = prompter
+                .ask({
+                envName: ctx.envName,
+                field: ctx.field,
+                masked: maskedFields.has(ctx.field),
+                signal: ctx.signal,
+            })
+                .catch((error) => {
+                answers.delete(key);
+                throw error instanceof ResolveError
+                    ? error
+                    : new ResolveError(ctx.envName, ctx.field, 'the prompt failed');
+            });
+            answers.set(key, answer);
+            return answer;
+        },
+        confirm(ctx) {
+            const write = ctx.purpose === 'write' || ctx.purpose === 'drop';
+            const remembered = write ? undefined : confirmed.get(ctx.envName);
+            if (remembered)
+                return remembered;
+            const field = ctx.purpose === 'drop' ? 'drop' : write ? 'write' : 'confirm';
+            if (!ctx.interactive)
+                return Promise.reject(new PromptRequiredError(ctx.envName, field));
+            const challenge = challengeWords();
+            const attempt = async (left) => {
+                const typed = await prompter.ask({
+                    envName: ctx.envName,
+                    field,
+                    masked: false,
+                    challenge,
+                    signal: ctx.signal,
+                });
+                if (sameWords(typed, challenge))
+                    return;
+                if (left > 1)
+                    return attempt(left - 1);
+                throw new ResolveError(ctx.envName, field, 'the words typed were not the ones shown');
+            };
+            const done = attempt(CONFIRM_ATTEMPTS).catch((error) => {
+                if (!write)
+                    confirmed.delete(ctx.envName);
+                throw error instanceof ResolveError
+                    ? error
+                    : new ResolveError(ctx.envName, field, 'the prompt failed');
+            });
+            if (!write)
+                confirmed.set(ctx.envName, done);
+            return done;
+        },
+        describe: () => 'prompt',
+        forget(envName) {
+            const prefix = keyOf(envName, '');
+            for (const key of answers.keys())
+                if (key.startsWith(prefix))
+                    answers.delete(key);
+        },
+    };
+}

package/dist/config/resolvers/stored.js

@@ -0,0 +1,13 @@
+import { ResolveError } from './types.js';
+// The value is a secret the user keeps in the local store, under the given key.
+export const createStoredResolver = (store) => ({
+    kind: 'stored',
+    resolve({ stored }, ctx) {
+        const value = store.getSecret(stored);
+        if (!value) {
+            return Promise.reject(new ResolveError(ctx.envName, ctx.field, `no stored secret named "${stored}"`));
+        }
+        return Promise.resolve(value);
+    },
+    describe: ({ stored }) => `stored: ${stored}`,
+});

package/dist/config/resolvers/types.js

@@ -0,0 +1,18 @@
+// How a config `Value` becomes a string at connect time. Resolved values live in memory only:
+// nothing here, including every error message, may contain one.
+export class ResolveError extends Error {
+    envName;
+    field;
+    reason;
+    denied;
+    name = 'ResolveError';
+    constructor(envName, field, reason, 
+    // The server refused this user: the value exists but they may not read it.
+    denied = false) {
+        super(`${envName}.${field}: ${reason}`);
+        this.envName = envName;
+        this.field = field;
+        this.reason = reason;
+        this.denied = denied;
+    }
+}

package/dist/config/resolvers/vault.js

@@ -0,0 +1,283 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ResolveError } from './types.js';
+export const vaultTimeoutMs = 10_000;
+// A token that expires within this many ms is replaced before it is used.
+const expiryMarginMs = 30_000;
+// "secret/data/db/prod#password" → the KV v2 API path and the key inside the secret's data.
+const split = (ref) => {
+    const at = ref.lastIndexOf('#');
+    return { path: ref.slice(0, at), key: ref.slice(at + 1) };
+};
+// "secret/data/psql-explorer/prod" → "secret/metadata/psql-explorer/prod", where listing happens.
+export function metadataPath(dataPath) {
+    const parts = dataPath.split('/');
+    const at = parts.indexOf('data', 1);
+    if (at < 1)
+        return undefined;
+    parts[at] = 'metadata';
+    return parts.join('/');
+}
+/**
+ * Values from a HashiCorp Vault KV v2 secret: `source: vault` with `value: "<api path>#<key>"`, for example
+ * `secret/data/db/prod#password`. Needs VAULT_ADDR (VAULT_NAMESPACE is sent when set) and a token,
+ * taken from the first of these that is available:
+ *
+ * 1. VAULT_TOKEN;
+ * 2. an AppRole login, when VAULT_ROLE_ID and VAULT_SECRET_ID are set;
+ * 3. a JWT login (`auth/jwt/login`), when VAULT_JWT and VAULT_ROLE are set;
+ * 4. the token in ~/.vault-token.
+ *
+ * A token from a login is held in memory only, and replaced by a new login when it has expired.
+ * A secret is fetched from Vault every time a value is looked up and never kept, so a rotated
+ * password is seen by the next use. No error message contains a value from Vault.
+ */
+export function createVaultClient(options = {}) {
+    const environment = () => options.env ?? process.env;
+    const tokenFile = options.tokenFile ?? join(homedir(), '.vault-token');
+    const timeoutMs = options.timeoutMs ?? vaultTimeoutMs;
+    const doFetch = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    let current;
+    const fail = (ctx, reason, denied = false) => new ResolveError(ctx.envName, ctx.field, reason, denied);
+    const address = (ctx) => {
+        const value = environment().VAULT_ADDR?.replace(/\/+$/, '');
+        if (!value)
+            throw fail(ctx, 'VAULT_ADDR is not set');
+        return value;
+    };
+    // One request to Vault, with the timeout, the lookup's abort signal and readable failures.
+    const send = async (ctx, path, init) => {
+        const base = address(ctx);
+        const headers = {};
+        if (init.token)
+            headers['X-Vault-Token'] = init.token;
+        const namespace = environment().VAULT_NAMESPACE;
+        if (namespace)
+            headers['X-Vault-Namespace'] = namespace;
+        if (init.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+        try {
+            return await doFetch(`${base}/v1/${path}`, {
+                method: init.method ?? 'GET',
+                headers,
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                signal,
+            });
+        }
+        catch (error) {
+            if (ctx.signal?.aborted)
+                throw fail(ctx, 'cancelled');
+            if (timeout.aborted) {
+                throw fail(ctx, `Vault at ${base} did not answer within ${timeoutMs / 1000}s`);
+            }
+            const code = error.cause?.code;
+            throw fail(ctx, `cannot reach Vault at ${base}${code ? ` (${code})` : ''}`);
+        }
+    };
+    const login = async (ctx, method, path, body) => {
+        const response = await send(ctx, path, { method: 'POST', body });
+        if (!response.ok) {
+            // Vault's own message is left out: it can echo what was sent.
+            throw fail(ctx, `Vault ${method} login was refused (HTTP ${response.status})`);
+        }
+        let auth;
+        try {
+            auth = (await response.json()).auth;
+        }
+        catch {
+            // Reported below.
+        }
+        if (typeof auth?.client_token !== 'string' || auth.client_token === '') {
+            throw fail(ctx, `Vault ${method} login returned no token`);
+        }
+        const lease = typeof auth.lease_duration === 'number' ? auth.lease_duration : 0;
+        return {
+            value: auth.client_token,
+            expiresAt: lease > 0 ? now() + lease * 1000 - expiryMarginMs : undefined,
+            fromLogin: true,
+        };
+    };
+    const acquire = async (ctx) => {
+        const settings = environment();
+        if (settings.VAULT_TOKEN)
+            return { value: settings.VAULT_TOKEN, fromLogin: false };
+        if (settings.VAULT_ROLE_ID && settings.VAULT_SECRET_ID) {
+            return login(ctx, 'AppRole', 'auth/approle/login', {
+                role_id: settings.VAULT_ROLE_ID,
+                secret_id: settings.VAULT_SECRET_ID,
+            });
+        }
+        if (settings.VAULT_JWT && settings.VAULT_ROLE) {
+            return login(ctx, 'JWT', 'auth/jwt/login', {
+                role: settings.VAULT_ROLE,
+                jwt: settings.VAULT_JWT,
+            });
+        }
+        try {
+            const content = (await readFile(tokenFile, 'utf8')).trim();
+            if (content)
+                return { value: content, fromLogin: false };
+        }
+        catch {
+            // Reported below, the same as an empty file.
+        }
+        throw fail(ctx, 'no Vault token: set VAULT_TOKEN, VAULT_ROLE_ID and VAULT_SECRET_ID, VAULT_JWT and VAULT_ROLE, or log in with the vault CLI (~/.vault-token)');
+    };
+    // The token in use; a login that has expired, or that was refused, is done again.
+    const token = async (ctx, replace) => {
+        const seen = current;
+        if (seen) {
+            const held = await seen.catch(() => undefined);
+            const usable = held && (held.expiresAt === undefined || now() < held.expiresAt);
+            // `replace` was refused; if another lookup has already got a new token, use that.
+            if (usable && held !== replace)
+                return held;
+            if (current === seen)
+                current = undefined;
+        }
+        current ??= acquire(ctx);
+        const started = current;
+        started.catch(() => {
+            if (current === started)
+                current = undefined;
+        });
+        return started;
+    };
+    // An authenticated request. A token from a login can be revoked or expire early: log in again,
+    // once.
+    const authed = async (ctx, path, init, used, canRetry = true) => {
+        address(ctx);
+        const held = used ?? (await token(ctx, undefined));
+        const response = await send(ctx, path, { ...init, token: held.value });
+        if (response.status === 403 && held.fromLogin && canRetry) {
+            return authed(ctx, path, init, await token(ctx, held), false);
+        }
+        if (response.status === 403 && !held.fromLogin && !(await tokenWorks(ctx, held))) {
+            // An expired or revoked token also answers 403, which would pass for missing access.
+            // Forget it, so a `vault login` made meanwhile is picked up by the next lookup.
+            current = undefined;
+            throw fail(ctx, 'the Vault token is expired or not valid: log in again (vault login) or set a new VAULT_TOKEN');
+        }
+        return response;
+    };
+    // Whether Vault still accepts a token we were given and cannot renew. Every valid token may look
+    // itself up, so a refusal here means the token is bad; any other answer is taken as good.
+    const checked = new WeakMap();
+    const tokenWorks = (ctx, held) => {
+        let result = checked.get(held);
+        if (!result) {
+            result = send(ctx, 'auth/token/lookup-self', { token: held.value }).then((response) => response.status !== 403 && response.status !== 401);
+            checked.set(held, result);
+            result.catch(() => checked.delete(held));
+        }
+        return result;
+    };
+    // The JSON body of a successful answer; other answers become readable errors.
+    const call = async (ctx, path, init, what) => {
+        const response = await authed(ctx, path, init);
+        if (response.status === 403)
+            throw fail(ctx, `permission denied for ${path}`, true);
+        if (response.status === 404)
+            throw fail(ctx, `${what} ${path} not found`);
+        if (!response.ok)
+            throw fail(ctx, `Vault returned HTTP ${response.status} for ${path}`);
+        try {
+            const body = (await response.json());
+            if (typeof body === 'object' && body !== null)
+                return body;
+        }
+        catch {
+            // Reported below.
+        }
+        throw fail(ctx, `unexpected response from Vault for ${path}`);
+    };
+    const fetchSecret = async (path, ctx) => {
+        const body = await call(ctx, path, {}, 'secret');
+        const data = body.data?.data;
+        if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+            return data;
+        }
+        throw fail(ctx, `unexpected response from Vault for ${path} (is it a KV v2 path, "…/data/…"?)`);
+    };
+    // --- The config's own secrets: read, list and write ---
+    const kvContext = (path, signal) => ({
+        envName: 'vault',
+        field: path,
+        configDir: '',
+        interactive: false,
+        signal,
+    });
+    const kv = {
+        async read(path, signal) {
+            const ctx = kvContext(path, signal);
+            const response = await authed(ctx, path, {});
+            if (response.status === 404)
+                return undefined;
+            if (response.status === 403)
+                throw fail(ctx, `permission denied for ${path}`, true);
+            if (!response.ok)
+                throw fail(ctx, `Vault returned HTTP ${response.status} for ${path}`);
+            let body;
+            try {
+                body = (await response.json());
+            }
+            catch {
+                // Reported below.
+            }
+            const data = body?.data?.data;
+            if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+                // A soft-deleted version answers 404 with a body; anything else here is the wrong path type.
+                throw fail(ctx, `unexpected response from Vault for ${path} (is it a KV v2 path, "…/data/…"?)`);
+            }
+            const version = body?.data?.metadata?.version;
+            return { data: data, version: typeof version === 'number' ? version : 0 };
+        },
+        async list(path, signal) {
+            const ctx = kvContext(path, signal);
+            const metadata = metadataPath(path);
+            if (!metadata) {
+                throw fail(ctx, `${path} is not a KV v2 path (expected "<mount>/data/<path>")`);
+            }
+            const response = await authed(ctx, `${metadata}?list=true`, {});
+            if (response.status === 404)
+                return [];
+            if (response.status === 403)
+                throw fail(ctx, `permission denied to list ${metadata}`, true);
+            if (!response.ok)
+                throw fail(ctx, `Vault returned HTTP ${response.status} for ${metadata}`);
+            try {
+                const keys = (await response.json()).data?.keys;
+                if (Array.isArray(keys))
+                    return keys.filter((key) => typeof key === 'string');
+            }
+            catch {
+                // Reported below.
+            }
+            throw fail(ctx, `unexpected response from Vault for ${metadata}`);
+        },
+    };
+    const resolver = {
+        kind: 'vault',
+        async resolve(ref, ctx) {
+            const { path, key } = split(ref.vault);
+            const data = await fetchSecret(path, ctx);
+            const value = data[key];
+            if (value === undefined || value === null) {
+                throw fail(ctx, `key ${key} not in ${path}`);
+            }
+            if (typeof value === 'object')
+                throw fail(ctx, `key ${key} in ${path} is not a string`);
+            const text = String(value);
+            if (text === '')
+                throw fail(ctx, `key ${key} in ${path} is empty`);
+            return text;
+        },
+        describe: ({ vault }) => `vault: ${vault}`,
+    };
+    return { resolver, kv };
+}
+export const createVaultResolver = (options = {}) => createVaultClient(options).resolver;

package/dist/config/schema.js

@@ -0,0 +1,24 @@
+// The shared config, parsed and validated but not resolved: a field is either a literal or a
+// reference to where its value comes from, which is looked up at connect time. It is a base path
+// holding one `<environment>/explorer.yaml` per environment, either in a directory or in Vault
+// (see source.ts).
+export const tiers = ['production', 'reference', 'demo', 'development', 'local'];
+export const authModes = ['password', 'none'];
+export const tlsModes = ['disable', 'require', 'verify-ca', 'verify-full'];
+export const refKinds = ['env', 'file', 'prompt', 'stored', 'vault'];
+export const sourceNames = ['plaintext', 'inline', ...refKinds];
+// The schema browsing starts in when an environment does not name one.
+export const defaultSchemaName = 'public';
+export const describeProblem = (problem) => `${problem.path || 'config'}${problem.line === undefined ? '' : ` (line ${problem.line})`}: ${problem.message}`;
+export class ConfigError extends Error {
+    file;
+    problems;
+    name = 'ConfigError';
+    constructor(
+    // What was being read: the base path, or one file of it.
+    file, problems) {
+        super(`Invalid config ${file}:\n${problems.map((problem) => `  ${describeProblem(problem)}`).join('\n')}`);
+        this.file = file;
+        this.problems = problems;
+    }
+}

package/dist/config/source.js

@@ -0,0 +1,105 @@
+// Where the shared config is stored. A base path holds one `<environment>/explorer.yaml` per
+// environment, in a directory or in Vault:
+//
+//   ./config                        vault:secret/data/psql-explorer
+//   ./config/prod/explorer.yaml     secret/data/psql-explorer/prod      key explorer.yaml
+//
+// Listing the base is how environments are discovered, so what a person can see in Vault follows
+// their policy. Nothing here parses the YAML.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { metadataPath, ResolveError } from './resolvers/index.js';
+export const configFileName = 'explorer.yaml';
+export const vaultPrefix = 'vault:';
+/** The config could not be read; `denied` when Vault refuses this user. */
+export class SourceError extends Error {
+    denied;
+    name = 'SourceError';
+    constructor(message, denied = false) {
+        super(message);
+        this.denied = denied;
+    }
+}
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+const localSource = (base) => {
+    const fileOf = (name) => join(base, name, configFileName);
+    const read = async (path, dir) => {
+        try {
+            return { text: await readFile(path, 'utf8'), label: path, dir };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw new SourceError(`cannot read ${path}: ${reason(error)}`);
+        }
+    };
+    return {
+        base,
+        async list() {
+            let entries;
+            try {
+                entries = await readdir(base, { withFileTypes: true });
+            }
+            catch (error) {
+                const code = error.code;
+                throw new SourceError(code === 'ENOENT' ? 'directory not found' : `cannot read the directory: ${reason(error)}`);
+            }
+            const names = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith('.'))
+                    continue;
+                // Folders without an explorer.yaml (certificates, say) are not environments.
+                if (await read(fileOf(entry.name), join(base, entry.name)))
+                    names.push(entry.name);
+            }
+            return names.sort();
+        },
+        readEnvironment: (name) => read(fileOf(name), join(base, name)),
+    };
+};
+const vaultSource = (path, vault) => {
+    const base = `${vaultPrefix}${path}`;
+    const secretOf = (name) => `${path}/${name}`;
+    const labelOf = (name) => `${secretOf(name)}#${configFileName}`;
+    // Vault says why in a ResolveError; only the reason is wanted here.
+    const wrap = async (work) => {
+        try {
+            return await work;
+        }
+        catch (error) {
+            if (error instanceof ResolveError)
+                throw new SourceError(error.reason, error.denied);
+            throw error;
+        }
+    };
+    const read = async (name) => {
+        const secret = await wrap(vault.kv.read(secretOf(name)));
+        if (!secret)
+            return undefined;
+        const text = secret.data[configFileName];
+        if (typeof text !== 'string') {
+            throw new SourceError(`${secretOf(name)} has no ${configFileName} key`);
+        }
+        return { text, label: labelOf(name), dir: process.cwd() };
+    };
+    return {
+        base,
+        async list() {
+            const keys = await wrap(vault.kv.list(path));
+            // A trailing "/" is a folder; an environment is a secret of its own.
+            return keys.filter((key) => !key.endsWith('/')).sort();
+        },
+        readEnvironment: (name) => read(name),
+    };
+};
+/** The source for a base path: "vault:<KV v2 data path>", else a directory. Throws SourceError if it is malformed. */
+export function createSource(base, vault) {
+    if (base.startsWith(vaultPrefix)) {
+        const path = base.slice(vaultPrefix.length).replace(/^\/+|\/+$/g, '');
+        if (!path || !metadataPath(path)) {
+            throw new SourceError('a Vault base path looks like vault:secret/data/psql-explorer (a KV v2 "<mount>/data/<path>")');
+        }
+        return vaultSource(path, vault);
+    }
+    return localSource(resolve(base));
+}

package/dist/db/connect.js

@@ -0,0 +1,55 @@
+import pg from 'pg';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const DEFAULT_STATEMENT_TIMEOUT_MS = 30_000;
+// Every value comes back as the text Postgres sends, as psql shows it: no Date shifted into the
+// local time zone, no bigint rounded through a JS number.
+const asText = (value) => value;
+export const textTypes = {
+    getTypeParser: (() => asText),
+};
+/** Maps TLS settings to the `ssl` option of the pg driver. */
+export function sslOptions(tls) {
+    if (tls.mode === 'disable')
+        return false;
+    const client = {
+        ...(tls.cert === undefined ? {} : { cert: tls.cert }),
+        ...(tls.key === undefined ? {} : { key: tls.key }),
+        ...(tls.keyPassphrase === undefined ? {} : { passphrase: tls.keyPassphrase }),
+    };
+    if (tls.mode === 'require')
+        return { rejectUnauthorized: false, ...client };
+    const verified = {
+        rejectUnauthorized: true,
+        ...(tls.ca === undefined ? {} : { ca: tls.ca }),
+        ...client,
+    };
+    // verify-ca checks the chain only, not that the certificate names this host.
+    return tls.mode === 'verify-ca' ? { ...verified, checkServerIdentity: () => undefined } : verified;
+}
+/**
+ * Builds, without connecting, the pg client every part of the explorer uses to reach a database.
+ * The caller connects it and must end it.
+ */
+export function createClient(params, { timeoutMs = DEFAULT_TIMEOUT_MS, statementTimeoutMs = DEFAULT_STATEMENT_TIMEOUT_MS, readOnly = false, } = {}) {
+    // Startup parameters, so they hold from the first statement on.
+    const settings = [
+        ...(readOnly ? ['default_transaction_read_only=on'] : []),
+        ...(statementTimeoutMs === null ? [] : [`statement_timeout=${statementTimeoutMs}`]),
+    ];
+    const client = new pg.Client({
+        host: params.host,
+        port: params.port,
+        database: params.database,
+        user: params.username,
+        password: params.password,
+        ssl: sslOptions(params.tls),
+        connectionTimeoutMillis: timeoutMs,
+        application_name: 'psql-explorer',
+        types: textTypes,
+        ...(settings.length > 0 ? { options: settings.map((setting) => `-c ${setting}`).join(' ') } : {}),
+    });
+    // A connection the server drops later (a restart, an idle timeout) emits 'error'; without a
+    // listener that would crash the process. The next query reports it instead.
+    client.on('error', () => undefined);
+    return client;
+}

package/dist/db/identifiers.js

@@ -0,0 +1,6 @@
+/** Quotes a Postgres identifier (schema, table...), so a name from config can never alter a query. */
+export function quoteIdentifier(name) {
+    if (!name || name.includes('\0'))
+        throw new Error(`Invalid identifier "${name}"`);
+    return `"${name.replaceAll('"', '""')}"`;
+}

package/dist/db/paths.js

@@ -0,0 +1,14 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const databaseFileName = 'explorer.db';
+export const configVariable = 'PSQL_EXPLORER_CONFIG';
+// PSQL_EXPLORER_CONFIG (the directory holding explorer.db) wins, then the XDG config dir, then
+// ~/.config. Empty values count as unset, as the XDG spec asks.
+export function dataDir(env = process.env, home = homedir()) {
+    if (env[configVariable])
+        return env[configVariable];
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, 'psql-explorer');
+    return join(home, '.config', 'psql-explorer');
+}
+export const databaseFile = (dir) => join(dir, databaseFileName);