@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/config/load.js

@@ -0,0 +1,324 @@
+import { isMap, isScalar, LineCounter, parseDocument } from 'yaml';
+import { authModes, ConfigError, sourceNames, tiers, tlsModes, } from './schema.js';
+import { createSource, SourceError } from './source.js';
+export const environmentNamePattern = /^[a-z0-9][a-z0-9-_]*$/;
+const envVariablePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const vaultPattern = /^[^#\s]+#[^#\s]+$/;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const environmentsVariable = 'PSQL_EXPLORER_ENVIRONMENTS';
+/**
+ * Loads the shared config from the base path: `base` (--config), else $PSQL_EXPLORER_ENVIRONMENTS,
+ * else none, in which case the app only has local connections. Never throws for a bad config: what
+ * is wrong is in `error`, and the environments that are fine are still in `config`. An environment
+ * Vault will not let this user read is left out silently; that is how access is granted.
+ */
+export async function loadConfig(options) {
+    const given = options.base || (options.env ?? process.env)[environmentsVariable];
+    if (!given)
+        return {};
+    let source;
+    try {
+        source = createSource(given, options.vault);
+    }
+    catch (error) {
+        return { error: new ConfigError(given, [{ path: '', message: messageOf(error) }]) };
+    }
+    const problems = [];
+    const problem = (path, message, line) => {
+        problems.push({ path, message, ...(line === undefined ? {} : { line }) });
+    };
+    let names;
+    try {
+        options.onProgress?.('list of environments');
+        names = await source.list();
+    }
+    catch (error) {
+        // Nothing can be read from a base path that cannot be listed.
+        problem('', messageOf(error));
+        return { error: new ConfigError(source.base, problems), source };
+    }
+    const environments = [];
+    for (const [index, name] of names.entries()) {
+        options.onProgress?.(`${name} (${index + 1} of ${names.length})`);
+        if (!environmentNamePattern.test(name)) {
+            problem(name, `'${name}' is not a valid environment name; use lower-case letters, digits, - and _, starting with a letter or digit`);
+            continue;
+        }
+        try {
+            const file = await source.readEnvironment(name);
+            if (file)
+                environments.push(parseEnvironment(name, file.text, file.label, file.dir));
+        }
+        catch (error) {
+            if (error instanceof SourceError && error.denied)
+                continue;
+            for (const found of problemsOf(error, name))
+                problems.push(found);
+            if (!(error instanceof ConfigError))
+                problem(name, messageOf(error));
+        }
+    }
+    const config = { base: source.base, environments };
+    return {
+        config,
+        source,
+        ...(problems.length > 0 ? { error: new ConfigError(source.base, problems) } : {}),
+    };
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+// A ConfigError's problems, each under `prefix` so they say which file they are in.
+const problemsOf = (error, prefix) => error instanceof ConfigError
+    ? error.problems.map((found) => ({
+        ...found,
+        path: found.path ? `${prefix}.${found.path}` : prefix,
+    }))
+    : [];
+const parseYaml = (text, file) => {
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(text, { lineCounter });
+    if (doc.errors.length > 0) {
+        throw new ConfigError(file, doc.errors.map((error) => ({
+            path: '',
+            line: error.linePos?.[0].line,
+            // yaml appends the location and a code excerpt to the first line.
+            message: (error.message.split('\n')[0] ?? error.message).replace(/ at line \d+, column \d+:?$/, ''),
+        })));
+    }
+    return new Checker(doc, lineCounter);
+};
+// Parses and validates the text of one environment's file; `dir` is where its `file` references
+// are relative to. Problem paths are relative to the file ("tls.cert").
+export function parseEnvironment(name, text, file, dir) {
+    const checker = parseYaml(text, file);
+    const environment = checker.environment(name, checker.toJS(), dir);
+    if (checker.problems.length > 0 || !environment)
+        throw new ConfigError(file, checker.problems);
+    return environment;
+}
+class Checker {
+    doc;
+    lines;
+    problems = [];
+    constructor(doc, lines) {
+        this.doc = doc;
+        this.lines = lines;
+    }
+    toJS() {
+        return this.doc.toJS();
+    }
+    environment(name, raw, dir) {
+        const path = [];
+        if (!isRecord(raw))
+            return this.fail(path, 'must be a mapping');
+        const before = this.problems.length;
+        this.unknownKeys(raw, path, [
+            'tier',
+            'protected',
+            'host',
+            'port',
+            'database',
+            'schema',
+            'username',
+            'password',
+            'auth',
+            'tls',
+            'readOnly',
+            'confirm',
+            'seeder',
+            'designer',
+        ]);
+        const tier = this.choice(raw.tier, [...path, 'tier'], tiers, undefined);
+        const auth = this.choice(raw.auth, [...path, 'auth'], authModes, 'password');
+        const host = this.value(raw.host, [...path, 'host'], { required: true });
+        const port = this.value(raw.port, [...path, 'port'], { required: true, number: true });
+        const database = this.value(raw.database, [...path, 'database'], { required: true });
+        const schema = this.value(raw.schema, [...path, 'schema']);
+        const username = this.value(raw.username, [...path, 'username'], { required: true });
+        const password = this.value(raw.password, [...path, 'password']);
+        const isProtected = raw.protected === undefined ? undefined : this.flag(raw.protected, [...path, 'protected']);
+        const readOnly = raw.readOnly === undefined ? undefined : this.flag(raw.readOnly, [...path, 'readOnly']);
+        const confirm = raw.confirm === undefined ? undefined : this.flag(raw.confirm, [...path, 'confirm']);
+        const seeder = raw.seeder === undefined ? undefined : this.flag(raw.seeder, [...path, 'seeder']);
+        const designer = raw.designer === undefined ? undefined : this.flag(raw.designer, [...path, 'designer']);
+        const tls = this.tls(raw.tls, [...path, 'tls']);
+        if (auth === 'password' && raw.password === undefined) {
+            this.add([...path, 'password'], 'is required when auth is password');
+        }
+        if (auth === 'none' && raw.password !== undefined) {
+            this.add([...path, 'password'], 'must not be set when auth is none', true);
+        }
+        if (this.problems.length > before)
+            return undefined;
+        const guarded = isProtected ?? tier === 'production';
+        return {
+            name,
+            dir,
+            tier: tier,
+            protected: guarded,
+            readOnly: readOnly ?? guarded,
+            confirm: confirm ?? guarded,
+            seeder: seeder ?? (tier === 'development' || tier === 'local'),
+            designer: designer ?? (tier === 'development' || tier === 'local'),
+            host: host,
+            port: port,
+            database: database,
+            ...(schema === undefined ? {} : { schema }),
+            username: username,
+            auth: auth,
+            ...(password === undefined ? {} : { password }),
+            tls: tls,
+        };
+    }
+    tls(raw, path) {
+        if (raw === undefined)
+            return { mode: 'disable' };
+        if (!isRecord(raw))
+            return this.fail(path, 'must be a mapping');
+        const before = this.problems.length;
+        this.unknownKeys(raw, path, ['mode', 'ca', 'cert', 'key', 'keyPassphrase']);
+        const mode = this.choice(raw.mode, [...path, 'mode'], tlsModes, 'disable');
+        const ca = this.value(raw.ca, [...path, 'ca']);
+        const cert = this.value(raw.cert, [...path, 'cert']);
+        const key = this.value(raw.key, [...path, 'key']);
+        const keyPassphrase = this.value(raw.keyPassphrase, [...path, 'keyPassphrase']);
+        if (raw.cert !== undefined && raw.key === undefined) {
+            this.add([...path, 'cert'], 'cert and key must be given together', true);
+        }
+        if (raw.key !== undefined && raw.cert === undefined) {
+            this.add([...path, 'key'], 'cert and key must be given together', true);
+        }
+        if ((mode === 'verify-ca' || mode === 'verify-full') && raw.ca === undefined) {
+            this.add([...path, 'ca'], `is required when tls mode is ${mode}`);
+        }
+        if (this.problems.length > before)
+            return undefined;
+        const optional = { ca, cert, key, keyPassphrase };
+        return {
+            mode: mode,
+            ...Object.fromEntries(Object.entries(optional).filter(([, value]) => value !== undefined)),
+        };
+    }
+    // A literal text setting.
+    text(raw, path, options) {
+        if (raw === undefined) {
+            return options.required ? this.fail(path, 'is required') : options.fallback;
+        }
+        if (typeof raw !== 'string' || raw.trim() === '') {
+            return this.fail(path, 'must be a non-empty string');
+        }
+        if (options.maxBytes !== undefined && Buffer.byteLength(raw) > options.maxBytes) {
+            return this.fail(path, `must be at most ${options.maxBytes} bytes`);
+        }
+        return raw;
+    }
+    // A setting that is always a literal, one of a fixed set.
+    choice(raw, path, allowed, fallback) {
+        if (raw === undefined)
+            return fallback ?? this.fail(path, 'is required');
+        if (typeof raw === 'string' && allowed.includes(raw))
+            return raw;
+        return this.fail(path, `must be one of: ${allowed.join(', ')}`);
+    }
+    flag(raw, path) {
+        if (raw === undefined)
+            return false;
+        return typeof raw === 'boolean' ? raw : this.fail(path, 'must be true or false');
+    }
+    // A literal, or a mapping of `source` and `value` saying where the value comes from.
+    value(raw, path, options = {}) {
+        if (raw === undefined)
+            return options.required ? this.fail(path, 'is required') : undefined;
+        if (typeof raw === 'string') {
+            return raw === '' ? this.fail(path, 'must not be empty') : raw;
+        }
+        if (typeof raw === 'number' && options.number)
+            return raw;
+        if (isRecord(raw))
+            return this.source(raw, path, options);
+        const hint = options.number ? 'a number, a string' : 'a string';
+        return this.fail(path, typeof raw === 'number'
+            ? 'must be a string (put it in quotes) or a mapping with source and value'
+            : `must be ${hint} or a mapping with source and value`);
+    }
+    source(raw, path, options) {
+        const allowed = sourceNames.join(', ');
+        this.unknownKeys(raw, path, ['source', 'value']);
+        const named = raw.source;
+        if (named === undefined)
+            return this.fail(path, `needs a source: one of ${allowed}`);
+        const at = [...path, 'source'];
+        if (typeof named !== 'string' || !sourceNames.includes(named)) {
+            return this.fail(at, `unknown source; use one of: ${allowed}`);
+        }
+        const valueAt = [...path, 'value'];
+        const value = raw.value;
+        if (named === 'prompt') {
+            return value === undefined
+                ? { prompt: true }
+                : this.fail(valueAt, 'must not be given: the value is asked for', true);
+        }
+        if (value === undefined)
+            return this.fail(valueAt, 'is required');
+        switch (named) {
+            case 'plaintext':
+            case 'inline':
+                if (typeof value === 'number' && options.number)
+                    return value;
+                return typeof value === 'string' && value !== ''
+                    ? value
+                    : this.fail(valueAt, 'must be the text itself (put a number in quotes)');
+            case 'env':
+                return typeof value === 'string' && envVariablePattern.test(value)
+                    ? { env: value }
+                    : this.fail(valueAt, 'must be an environment variable name');
+            case 'file':
+                return typeof value === 'string' && value !== ''
+                    ? { file: value }
+                    : this.fail(valueAt, 'must be a file path');
+            case 'stored':
+                return typeof value === 'string' && value !== ''
+                    ? { stored: value }
+                    : this.fail(valueAt, 'must be the name of a stored secret');
+            case 'vault':
+                return typeof value === 'string' && vaultPattern.test(value)
+                    ? { vault: value }
+                    : this.fail(valueAt, 'must look like "path#key", e.g. secret/data/db/prod#password');
+        }
+    }
+    unknownKeys(raw, path, allowed) {
+        for (const key of Object.keys(raw)) {
+            if (!allowed.includes(key)) {
+                this.add([...path, key], `unknown key; expected one of: ${allowed.join(', ')}`, true);
+            }
+        }
+    }
+    fail(path, message, atKey = false) {
+        this.add(path, message, atKey);
+        return undefined;
+    }
+    add(path, message, atKey = false) {
+        this.problems.push({ path: path.join('.'), line: this.lineOf(path, atKey), message });
+    }
+    // The line of the value at `path` (or of its key), else of the nearest enclosing node that
+    // exists, so a missing field points at the mapping it should be in.
+    lineOf(path, atKey) {
+        for (let length = path.length; length >= 0; length--) {
+            const here = path.slice(0, length);
+            let offset;
+            if (atKey && length === path.length && length > 0) {
+                const parent = this.doc.getIn(here.slice(0, -1), true);
+                const pair = isMap(parent)
+                    ? parent.items.find((item) => isScalar(item.key) && String(item.key.value) === here.at(-1))
+                    : undefined;
+                offset = isScalar(pair?.key) ? pair.key.range?.[0] : undefined;
+            }
+            else {
+                const node = length === 0 ? this.doc.contents : this.doc.getIn(here, true);
+                offset = node?.range?.[0];
+            }
+            if (offset !== undefined)
+                return this.lines.linePos(offset).line;
+        }
+        return undefined;
+    }
+}

package/dist/config/resolve-environment.js

@@ -0,0 +1,112 @@
+import { hostError, identifierError, passwordError, portError } from '../db/validate.js';
+import { defaultRegistry, describeValue, resolveValue, PromptRequiredError, ResolveError, } from './resolvers/index.js';
+import { defaultSchemaName } from './schema.js';
+/**
+ * Resolves the fields one at a time, in a fixed order (host, port, database, username, password,
+ * then the TLS fields) so any prompts appear in a predictable sequence. Every resolved value is
+ * checked with the same rules as the connection form; a failure is a ResolveError naming the
+ * field, and never contains the value.
+ */
+export async function resolveEnvironment(env, ctx) {
+    const registry = ctx.registry ?? defaultRegistry();
+    const fail = (field, reason) => new ResolveError(env.name, field, reason);
+    const resolve = (field, value) => resolveValue(value, {
+        envName: env.name,
+        field,
+        configDir: env.dir,
+        interactive: ctx.interactive,
+        signal: ctx.signal,
+    }, registry);
+    // Text from a file or a prompt often carries a stray newline or space.
+    const checked = async (field, value, rule) => {
+        const text = (await resolve(field, value)).trim();
+        const message = rule(text);
+        if (message)
+            throw fail(field, message);
+        return text;
+    };
+    const pem = async (field, value) => {
+        const text = await resolve(field, value);
+        if (!text.includes('-----BEGIN')) {
+            throw fail(field, 'is not PEM text (no "-----BEGIN" line found)');
+        }
+        return text;
+    };
+    if (env.confirm) {
+        // Before anything is looked up, so no secret is fetched for an environment nobody confirmed.
+        const prompt = registry.get('prompt');
+        if (!prompt)
+            throw new PromptRequiredError(env.name, 'confirm');
+        await prompt.confirm({ envName: env.name, interactive: ctx.interactive, signal: ctx.signal });
+    }
+    const host = await checked('host', env.host, hostError);
+    const port = Number(await checked('port', env.port, portError));
+    const database = await checked('database', env.database, (v) => identifierError('Database', v));
+    const schema = env.schema === undefined
+        ? defaultSchemaName
+        : await checked('schema', env.schema, (v) => identifierError('Schema', v));
+    const username = await checked('username', env.username, (v) => identifierError('Username', v));
+    let password;
+    if (env.auth === 'password' && env.password !== undefined) {
+        const text = await resolve('password', env.password);
+        const message = passwordError(text);
+        if (message)
+            throw fail('password', message);
+        password = text;
+    }
+    const tls = { mode: env.tls.mode };
+    // With TLS off these are never used, so they are not looked up (or prompted for).
+    if (env.tls.mode !== 'disable') {
+        if (env.tls.ca !== undefined)
+            tls.ca = await pem('tls.ca', env.tls.ca);
+        if (env.tls.cert !== undefined)
+            tls.cert = await pem('tls.cert', env.tls.cert);
+        if (env.tls.key !== undefined)
+            tls.key = await pem('tls.key', env.tls.key);
+        if (env.tls.keyPassphrase !== undefined) {
+            tls.keyPassphrase = await resolve('tls.keyPassphrase', env.tls.keyPassphrase);
+        }
+    }
+    return {
+        name: env.name,
+        tier: env.tier,
+        protected: env.protected,
+        readOnly: env.readOnly,
+        host,
+        port,
+        database,
+        username,
+        ...(password === undefined ? {} : { password }),
+        schema,
+        tls,
+    };
+}
+/** Where each field of the environment comes from, for display; never the values. */
+export function describeEnvironment(env, registry = defaultRegistry()) {
+    const labels = {};
+    const add = (field, value) => {
+        if (value === undefined)
+            return;
+        const ctx = { envName: env.name, field, configDir: '', interactive: false };
+        try {
+            labels[field] = describeValue(value, ctx, registry);
+        }
+        catch {
+            // A kind with no resolver yet still has a safe label: its name and reference.
+            const [kind = 'unknown', ref] = Object.entries(value)[0] ?? [];
+            labels[field] = kind === 'prompt' ? 'prompt' : `${kind}: ${String(ref)}`;
+        }
+    };
+    add('host', env.host);
+    add('port', env.port);
+    add('database', env.database);
+    add('schema', env.schema);
+    add('username', env.username);
+    if (env.auth === 'password')
+        add('password', env.password);
+    add('tls.ca', env.tls.ca);
+    add('tls.cert', env.tls.cert);
+    add('tls.key', env.tls.key);
+    add('tls.keyPassphrase', env.tls.keyPassphrase);
+    return labels;
+}

package/dist/config/resolvers/env.js

@@ -0,0 +1,12 @@
+import { ResolveError } from './types.js';
+export const createEnvResolver = (environment = process.env) => ({
+    kind: 'env',
+    resolve({ env }, ctx) {
+        const value = environment[env];
+        if (!value) {
+            return Promise.reject(new ResolveError(ctx.envName, ctx.field, `environment variable ${env} is not set`));
+        }
+        return Promise.resolve(value);
+    },
+    describe: ({ env }) => `env: ${env}`,
+});

package/dist/config/resolvers/file.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ResolveError } from './types.js';
+// The value is the UTF-8 content of a file, relative to the config file's directory.
+export const fileResolver = {
+    kind: 'file',
+    async resolve({ file }, ctx) {
+        const target = path.resolve(ctx.configDir, file);
+        let content;
+        try {
+            content = await readFile(target, { encoding: 'utf8', signal: ctx.signal });
+        }
+        catch (error) {
+            // Only the error code is reported: it is enough, and nothing in it can be file content.
+            const code = error.code;
+            throw new ResolveError(ctx.envName, ctx.field, `cannot read file ${file}${code ? ` (${code})` : ''}`);
+        }
+        if (content === '') {
+            throw new ResolveError(ctx.envName, ctx.field, `file ${file} is empty`);
+        }
+        return content;
+    },
+    describe: ({ file }) => `file: ${file}`,
+};

package/dist/config/resolvers/groups.js

@@ -0,0 +1 @@
+export {};

package/dist/config/resolvers/index.js

@@ -0,0 +1,49 @@
+import { refKinds } from '../schema.js';
+import { createEnvResolver } from './env.js';
+import { fileResolver } from './file.js';
+import { literalResolver } from './literal.js';
+import { createStoredResolver } from './stored.js';
+import { createVaultClient } from './vault.js';
+import { createPromptResolver } from './prompt.js';
+import { ResolveError } from './types.js';
+export { ResolveError } from './types.js';
+export { createEnvResolver } from './env.js';
+export { fileResolver } from './file.js';
+export { literalResolver } from './literal.js';
+export { createStoredResolver } from './stored.js';
+export { createVaultClient, createVaultResolver, vaultTimeoutMs, metadataPath, } from './vault.js';
+export { createPromptResolver, PromptRequiredError, } from './prompt.js';
+export const createRegistry = (resolvers) => new Map(resolvers.map((resolver) => [resolver.kind, resolver]));
+// `prompter` enables `prompt` values and `store` `stored` ones; without them those
+// fail with "no resolver".
+export const defaultRegistry = (environment, prompter, store, 
+// Share one Vault client (its login token) with whoever else reads from Vault.
+vault = createVaultClient({ env: environment })) => createRegistry([
+    literalResolver,
+    createEnvResolver(environment),
+    fileResolver,
+    vault.resolver,
+    ...(prompter ? [createPromptResolver(prompter)] : []),
+    ...(store ? [createStoredResolver(store)] : []),
+]);
+const kindOf = (value) => {
+    if (typeof value !== 'object')
+        return 'literal';
+    return refKinds.find((kind) => kind in value) ?? 'unknown';
+};
+const lookup = (registry, value, ctx) => {
+    const kind = kindOf(value);
+    const resolver = registry.get(kind);
+    if (!resolver) {
+        throw new ResolveError(ctx.envName, ctx.field, `no resolver for "${kind}" values`);
+    }
+    return resolver;
+};
+export async function resolveValue(value, ctx, registry = defaultRegistry()) {
+    const resolver = lookup(registry, value, ctx);
+    if (ctx.signal?.aborted)
+        throw new ResolveError(ctx.envName, ctx.field, 'cancelled');
+    return resolver.resolve(value, ctx);
+}
+// Where the value comes from, safe to show.
+export const describeValue = (value, ctx, registry = defaultRegistry()) => lookup(registry, value, ctx).describe(value);

package/dist/config/resolvers/literal.js

@@ -0,0 +1,7 @@
+// The value is written in the config file itself.
+export const literalResolver = {
+    kind: 'literal',
+    resolve: (ref) => Promise.resolve(String(ref)),
+    // The value may be a secret, so it is never echoed.
+    describe: () => 'literal',
+};