ardent-cli-beta 0.0.18 → 0.0.19

package/dist/branches/credentials.js

@@ -0,0 +1,188 @@
+import { APIError, API_URL, request } from '../api/client.js';
+import { DRIVERS } from './drivers.js';
+import { pauseFor, pollPauser } from './poll.js';
+import { terminalText } from '../terminal.js';
+export class CredentialIssueRefused extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+// The issuance refusals that come before any issuance is recorded: a request
+// refused with one of these left nothing to revoke.
+const sourceRoleIssueRefusals = new Set(['invalid_source_role', 'source_role_unsupported', 'source_role_held', 'source_role_revocation_pending']);
+// sourceRolePattern is the name the API accepts for a source role: an
+// unquoted lower-case PostgreSQL identifier that begins with neither pg_ nor
+// ardent. The CLI checks it before it records or sends anything, so a mistyped
+// name never reaches a recovery record.
+const sourceRolePattern = /^(?!pg_|ardent)[a-z_][a-z0-9_]{0,62}$/;
+export function validSourceRole(role) {
+    return sourceRolePattern.test(role);
+}
+export function refusedBeforeIssuance(error) {
+    return error instanceof CredentialIssueRefused && error.code !== undefined && sourceRoleIssueRefusals.has(error.code);
+}
+function credentialPath(issuanceID) {
+    return `/branch-credentials/${encodeURIComponent(issuanceID)}`;
+}
+function safeRequest(token, path, init) {
+    return request(token, path, init).catch((error) => {
+        if (error instanceof APIError) {
+            // A coded refusal carries the API's own explanation, such as why a
+            // source role cannot be issued; an uncoded one is reported by status.
+            const detail = error.code ? ` ${terminalText(error.message)} (${terminalText(error.code)})` : '';
+            const message = `Branch credential request failed (HTTP ${error.status}).${detail}`;
+            if (error.status >= 400 && error.status < 500)
+                throw new CredentialIssueRefused(message, error.code);
+            throw new Error(message);
+        }
+        throw new Error('Branch credential request failed. Check the API connection and try again.');
+    });
+}
+// sourceRole, when given, asks for a fresh branch-only password on that
+// source role instead of an issued public read/write role. A replay of the same
+// request must name the same role.
+export async function issueBranchCredential(token, branchID, requestID, sourceRole) {
+    const body = sourceRole === undefined
+        ? { request_id: requestID, access_profile: 'public_read_write_v1' }
+        : { request_id: requestID, source_role: sourceRole };
+    const result = await safeRequest(token, `/branches/${encodeURIComponent(branchID)}/credentials`, {
+        method: 'POST', body: JSON.stringify(body),
+    });
+    if (!result || typeof result.issuance_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(result.issuance_id) || result.status !== 'pending') {
+        throw new Error('Ardent API returned an invalid branch credential issuance.');
+    }
+    return result.issuance_id;
+}
+// stop, when given, ends the wait with its abort reason: a caller that learns
+// the branch failed has no delivery left to wait for. served, when given,
+// settles once the branch serves; the ten-minute deadline runs from then,
+// since the control plane delivers nothing before it, and until then the wait
+// is bounded by whatever bounds served.
+export async function waitForBranchCredential(token, issuanceID, stop, served) {
+    const bound = 10 * 60 * 1000;
+    let deadline = served ? Number.POSITIVE_INFINITY : Date.now() + bound;
+    served?.then(() => { deadline = Date.now() + bound; }, () => { });
+    // A 202 is re-read on the poll cadence; a 5xx or a lost response is retried
+    // two seconds later. A server failure the API reports as 202 is
+    // indistinguishable from pending here and gets the poll cadence;
+    // docs/DECISIONS.md section 16 says when: "the API answers 202 when it
+    // cannot load a delivered credential's connection details". Both pauses
+    // end with stop's reason as soon as it aborts.
+    const pollPause = pollPauser(stop);
+    const retryPause = () => pauseFor(2000, stop);
+    while (Date.now() < deadline) {
+        stop?.throwIfAborted();
+        // The API has JSON and plain-text pending bodies. HTTP 202 is the only
+        // pending signal; only HTTP 200 delivers the one-time URI.
+        let response;
+        try {
+            response = await fetch(new URL(credentialPath(issuanceID), `${API_URL}/`), {
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                signal: stop ? AbortSignal.any([stop, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+                redirect: 'error',
+            });
+        }
+        catch {
+            await retryPause();
+            continue;
+        }
+        if (response.status === 202) {
+            await response.body?.cancel();
+            await pollPause();
+            continue;
+        }
+        if (response.status >= 500) {
+            await response.body?.cancel();
+            await retryPause();
+            continue;
+        }
+        if (response.status === 409) {
+            // The branch's node refused the source role by name; the issuance is
+            // still revoked by the caller.
+            let refusal;
+            try {
+                refusal = await response.json();
+            }
+            catch {
+                refusal = undefined;
+            }
+            const fields = typeof refusal === 'object' && refusal !== null ? refusal : {};
+            if (typeof fields.error === 'string' && typeof fields.message === 'string') {
+                throw new Error(`${terminalText(fields.message)} (${terminalText(fields.error)})`);
+            }
+            throw new Error('Branch credential delivery was refused (HTTP 409).');
+        }
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            throw new Error(`Branch credential delivery failed (HTTP ${response.status}).`);
+        }
+        let result;
+        try {
+            result = await response.json();
+        }
+        catch {
+            throw new Error('Ardent API returned an invalid branch credential delivery.');
+        }
+        if (typeof result !== 'object' || result === null)
+            throw new Error('Ardent API returned an invalid branch credential delivery.');
+        const delivered = result;
+        const strings = delivered.connection_strings;
+        const stringsValid = strings === undefined || (typeof strings === 'object' && strings !== null && !Array.isArray(strings) &&
+            DRIVERS.every((driver) => typeof strings[driver] === 'string' && strings[driver] !== '') &&
+            strings.libpq === delivered.uri);
+        if (delivered.issuance_id !== issuanceID || typeof delivered.delivery_id !== 'string' || !delivered.delivery_id ||
+            typeof delivered.uri !== 'string' || !delivered.uri || !stringsValid)
+            throw new Error('Ardent API returned an invalid branch credential delivery.');
+        return delivered;
+    }
+    throw new Error('Timed out waiting for a branch credential. Check branch status before trying again.');
+}
+export async function acknowledgeBranchCredential(token, issuanceID, deliveryID) {
+    const deadline = Date.now() + 30_000;
+    while (true) {
+        try {
+            const result = await request(token, `${credentialPath(issuanceID)}/ack`, {
+                method: 'POST', body: JSON.stringify({ delivery_id: deliveryID }),
+            });
+            if (result !== undefined)
+                throw new Error('Ardent API returned an invalid branch credential acknowledgement.');
+            return;
+        }
+        catch (error) {
+            if (error instanceof APIError && error.status < 500) {
+                throw new Error(`Branch credential acknowledgement was refused (HTTP ${error.status}).`);
+            }
+            if (Date.now() >= deadline)
+                throw new Error('Branch credential acknowledgement could not be confirmed.');
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+    }
+}
+export async function revokeBranchCredential(token, issuanceID) {
+    const deadline = Date.now() + 30_000;
+    while (true) {
+        let response;
+        try {
+            response = await fetch(new URL(credentialPath(issuanceID), `${API_URL}/`), {
+                method: 'DELETE',
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(10_000),
+                redirect: 'error',
+            });
+            await response.body?.cancel();
+        }
+        catch {
+            // A lost response leaves the outcome unknown; the same issuance may be
+            // revoked again without creating another credential.
+        }
+        if (response?.status === 202)
+            return;
+        if (response && response.status < 500)
+            throw new Error(`Credential revocation was refused (HTTP ${response.status}).`);
+        if (Date.now() >= deadline)
+            throw new Error('Credential revocation could not be confirmed.');
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+}

package/dist/branches/drivers.d.ts

@@ -0,0 +1,6 @@
+export declare const DRIVERS: readonly ["libpq", "node", "jdbc", "prisma"];
+export type Driver = typeof DRIVERS[number];
+export type ConnectionStrings = Record<Driver, string>;
+export declare const CLIENT_REQUIREMENTS: Record<Driver, readonly string[]>;
+export declare function validDriver(value: string): value is Driver;
+export declare function connectionString(driver: Driver, uri: string, strings: ConnectionStrings | undefined): string;

package/dist/branches/drivers.js

@@ -0,0 +1,77 @@
+// A delivered credential names one connection string per driver family,
+// because no single PostgreSQL URI verifies the branch's certificate on every
+// driver: libpq asks for the platform's trusted roots with
+// sslrootcert=system, which node-postgres reads as a file, postgres.js sends to
+// the server, and pgjdbc cannot parse; and Prisma's engine verifies nothing
+// unless sslaccept=strict. Why the CLI prints only the form the user names is
+// docs/DECISIONS.md section 15, "Rejected: printing every form at once".
+export const DRIVERS = ['libpq', 'node', 'jdbc', 'prisma'];
+// Each form must still verify the server, so the CLI checks the TLS settings
+// the API sent before it prints one. A form that would connect without
+// verification is refused rather than passed on.
+const verified = {
+    libpq: (value) => postgresQuery(value, { sslmode: 'verify-full', sslrootcert: 'system' }),
+    node: (value) => postgresQuery(value, { sslmode: 'verify-full' }),
+    prisma: (value) => postgresQuery(value, { sslmode: 'require', sslaccept: 'strict' }),
+    jdbc: (value) => {
+        if (!value.startsWith('jdbc:postgresql://'))
+            return false;
+        let url;
+        try {
+            url = new URL(value.slice('jdbc:'.length));
+        }
+        catch {
+            return false;
+        }
+        const parameters = url.searchParams;
+        return Boolean(url.hostname && url.port) && !url.username && exactly(parameters, ['user', 'password', 'sslmode', 'sslfactory']) &&
+            Boolean(parameters.get('user') && parameters.get('password')) &&
+            parameters.get('sslmode') === 'verify-full' && parameters.get('sslfactory') === 'org.postgresql.ssl.DefaultJavaSSLFactory';
+    },
+};
+function postgresQuery(value, want) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return url.protocol === 'postgresql:' && Boolean(url.hostname && url.port && url.username && url.password) && !url.hash &&
+        exactly(url.searchParams, Object.keys(want)) && Object.entries(want).every(([key, setting]) => url.searchParams.get(key) === setting);
+}
+// exactly reports whether parameters holds each of keys once and nothing else,
+// so a repeated key cannot stand in for a missing one.
+function exactly(parameters, keys) {
+    const present = [...parameters.keys()];
+    return present.length === keys.length && keys.every((key) => parameters.getAll(key).length === 1);
+}
+// What a form needs in the client's own code or environment, which no
+// connection string can carry. The libpq form asks for the platform's trusted
+// roots, and several common clients cannot reach them unaided.
+export const CLIENT_REQUIREMENTS = {
+    libpq: [
+        'libpq 16 or newer: libpq 14 and 15 cannot check the server against the system\'s trusted roots.',
+        'pgx 5.7 or newer. pgx is pure Go, so libpq does not help it; an older pgx connects with --driver node.',
+        'psycopg binary wheels (psycopg[binary], psycopg2-binary): set SSL_CERT_FILE to the system CA bundle, for example /etc/ssl/certs/ca-certificates.crt. The wheel\'s bundled OpenSSL does not read the system trust store.',
+        'asyncpg: pass ssl=ssl.create_default_context() to asyncpg.connect. asyncpg reads sslrootcert only as a file path.',
+    ],
+    node: [],
+    jdbc: [],
+    prisma: [],
+};
+export function validDriver(value) {
+    return DRIVERS.includes(value);
+}
+// connectionString returns the delivered form for driver, refusing an absent
+// or unverifying one. An API that predates per-driver strings delivered only
+// the libpq form, as uri.
+export function connectionString(driver, uri, strings) {
+    const value = strings ? strings[driver] : (driver === 'libpq' ? uri : undefined);
+    if (value === undefined) {
+        throw new Error(`This Ardent API delivers no ${driver} connection string yet; only --driver libpq is available.`);
+    }
+    if (!verified[driver](value))
+        throw new Error(`Ardent API returned a ${driver} connection string that does not verify the server.`);
+    return value;
+}

package/dist/branches/env.d.ts

@@ -0,0 +1 @@
+export declare function writeBranchEnv(value: string, directory?: string): Promise<void>;

package/dist/branches/env.js

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+// Replace through a private sibling so a failed write cannot truncate .env.
+// This does not coordinate with other programs editing the file concurrently.
+export async function writeBranchEnv(value, directory = process.cwd()) {
+    const destination = join(directory, '.env');
+    const temporary = join(directory, `.env.${randomUUID()}.tmp`);
+    try {
+        let contents = '';
+        try {
+            const info = await lstat(destination);
+            if (!info.isFile() || info.nlink !== 1)
+                throw new Error('Unsafe destination');
+            contents = await readFile(destination, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (Object.hasOwn(parseEnv(contents), 'DATABASE_URL')) {
+            throw new Error('DATABASE_URL already exists in .env; remove it explicitly before retrying.');
+        }
+        const quote = ['\'', '"', '`'].find((candidate) => !value.includes(candidate));
+        if (!quote || /[\r\n\0]/.test(value))
+            throw new Error('Unsupported dotenv value');
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(`${contents}${contents && !contents.endsWith('\n') ? '\n' : ''}DATABASE_URL=${quote}${value}${quote}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+        const parent = await open(directory, 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('DATABASE_URL already exists'))
+            throw error;
+        // File system errors can include caller-controlled paths; never include the
+        // credential or raw error in terminal output.
+        throw new Error('Could not write DATABASE_URL to .env. Check the file type, permissions and available space.');
+    }
+    finally {
+        await unlink(temporary).catch(() => { });
+    }
+}

package/dist/branches/poll.d.ts

@@ -0,0 +1,3 @@
+export declare function pollIntervalMs(attempt: number): number;
+export declare function pollPauser(stop?: AbortSignal): () => Promise<void>;
+export declare function pauseFor(ms: number, stop?: AbortSignal): Promise<void>;

package/dist/branches/poll.js

@@ -0,0 +1,40 @@
+// The cadence for re-reading a branch result that is not ready yet: a workflow
+// still running, or a credential still pending. The first re-read comes 100 ms
+// after the first answer and the interval doubles to a one-second cap, so a
+// short wait ends soon after the result is ready and a long one costs at most
+// one read a second. docs/DECISIONS.md section 16, "A branch wait re-reads
+// fast, then once a second", is why the CLI polls at all and why at this
+// cadence. This is for "not ready" answers only; a failed
+// request keeps its own retry spacing at each call site.
+const FIRST_POLL_MS = 100;
+const MAX_POLL_MS = 1000;
+export function pollIntervalMs(attempt) {
+    if (!Number.isInteger(attempt) || attempt < 0)
+        throw new Error(`poll attempt must be a non-negative integer, got ${attempt}`);
+    return Math.min(FIRST_POLL_MS * 2 ** attempt, MAX_POLL_MS);
+}
+// pollPauser returns one wait's pause: each call sleeps the next interval.
+// stop, when given, is passed to every pause (pauseFor).
+export function pollPauser(stop) {
+    let attempt = 0;
+    return () => pauseFor(pollIntervalMs(attempt++), stop);
+}
+// pauseFor sleeps ms. When stop aborts, before or during the sleep, it rejects
+// at once with stop's reason, so a wait whose caller gave up sends nothing more.
+export function pauseFor(ms, stop) {
+    return new Promise((resolve, reject) => {
+        if (stop?.aborted) {
+            reject(stop.reason);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            reject(stop?.reason);
+        };
+        const timer = setTimeout(() => {
+            stop?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        stop?.addEventListener('abort', abort, { once: true });
+    });
+}

package/dist/branches/psql.d.ts

@@ -0,0 +1,14 @@
+interface ConnectionEnvironment {
+    PGHOST: string;
+    PGPORT: string;
+    PGDATABASE: string;
+    PGUSER: string;
+    PGPASSWORD: string;
+    PGSSLMODE: string;
+    PGSSLROOTCERT: string;
+}
+export declare function connectionEnvironment(uri: string): ConnectionEnvironment;
+export declare function libpqTooOld(found: string): string;
+export declare function checkPsql(): Promise<void>;
+export declare function runPsql(connection: ConnectionEnvironment): Promise<void>;
+export {};

package/dist/branches/psql.js

@@ -0,0 +1,159 @@
+import { spawn } from 'node:child_process';
+function terminalCommand(arguments_) {
+    if (process.platform === 'darwin')
+        return ['-q', '-e', '/dev/null', 'psql', ...arguments_];
+    if (process.platform === 'linux') {
+        // util-linux 2.39 requires -c; its later positional `-- command` form is
+        // unavailable on Ubuntu 24.04. Every argument here is a fixed CLI option.
+        const command = ['psql', ...arguments_].map((argument) => `'${argument.replaceAll("'", "'\\''")}'`).join(' ');
+        return ['-q', '-e', '-c', command, '/dev/null'];
+    }
+    throw new Error('Branch connect requires macOS or Linux with the system script utility.');
+}
+export function connectionEnvironment(uri) {
+    let url;
+    let database;
+    let user;
+    let password;
+    try {
+        url = new URL(uri);
+        database = decodeURIComponent(url.pathname.slice(1));
+        user = decodeURIComponent(url.username);
+        password = decodeURIComponent(url.password);
+    }
+    catch {
+        throw new Error('Ardent API returned an invalid branch connection.');
+    }
+    const parameters = [...url.searchParams.entries()];
+    const controls = /[\u0000-\u001f\u007f]/;
+    // A terminating environment's username is <role>+<api key>, which its node
+    // proxy splits; a passthrough environment's is the role alone, because no
+    // proxy is there to split it. Either way neither half may be empty.
+    const [role, ...apiKey] = user.split('+');
+    if (url.protocol !== 'postgresql:' || !url.hostname || !url.port || !database || database.includes('/') ||
+        !role || apiKey.length > 1 || apiKey[0] === '' || !password ||
+        [database, user, password].some((value) => controls.test(value)) || url.hash || parameters.length !== 2 ||
+        url.searchParams.get('sslmode') !== 'verify-full' || url.searchParams.get('sslrootcert') !== 'system') {
+        throw new Error('Ardent API returned an unsupported branch connection.');
+    }
+    return {
+        PGHOST: url.hostname,
+        PGPORT: url.port,
+        PGDATABASE: database,
+        PGUSER: user,
+        PGPASSWORD: password,
+        PGSSLMODE: 'verify-full',
+        PGSSLROOTCERT: 'system',
+    };
+}
+// libpqTooOld names why an older libpq cannot connect and how to fix it. A
+// branch's certificate is from a public CA, so verifying it means trusting the
+// platform's roots, which a URI asks for with sslrootcert=system; libpq reads
+// that value only from 16 on, and an older one looks for a file named
+// "system". A packaged psql requires a libpq at least its own version, so the
+// psql version is the floor checked before any credential is issued; the TLS
+// refusal itself is recognised too, for a psql linked against an older libpq.
+export function libpqTooOld(found) {
+    return `${found} cannot verify Ardent's certificate: branch connect needs psql 16 or newer, with libpq 16 or newer, ` +
+        'because only libpq 16 and later check a server against the system\'s trusted roots (sslrootcert=system). ' +
+        'libpq 14 and 15 are the defaults on Ubuntu 22.04 and Debian 12. Install the PostgreSQL 16 or newer client ' +
+        '(for example postgresql-client-17 from apt.postgresql.org, or brew install libpq), then retry. ' +
+        'An application driver needs no psql: run ardent-beta branch connect --print --driver <libpq|node|jdbc|prisma>.';
+}
+const libpqRefusedSystemRoots = /root certificate file "system" does not exist/;
+export async function checkPsql() {
+    await new Promise((resolve, reject) => {
+        const child = spawn('script', terminalCommand(['--version']), { stdio: ['inherit', 'pipe', 'ignore'] });
+        let version = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { version += chunk.slice(0, 512 - version.length); });
+        child.once('error', () => reject(new Error('Install psql 16+ and the system script utility before connecting to a branch.')));
+        child.once('close', (code) => {
+            const major = /psql \(PostgreSQL\) (\d+)(?:\.|\s|$)/.exec(version)?.[1];
+            if (code === 0 && major && Number(major) >= 16)
+                resolve();
+            else if (code === 0 && major)
+                reject(new Error(libpqTooOld(`psql ${major}`)));
+            else
+                reject(new Error('Branch connect requires psql 16 or newer and the system script utility.'));
+        });
+    });
+}
+export async function runPsql(connection) {
+    // The API key is embedded in PGUSER. Neither the URI nor PGUSER reaches argv.
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('PG')));
+    await new Promise((resolve, reject) => {
+        const child = spawn('script', terminalCommand(['-X', '-v', 'PROMPT1=ardent=> ', '-v', 'PROMPT2=ardent-> ', '-v', 'PROMPT3=ardent>> ']), {
+            env: { ...environment, ...connection },
+            // script gives psql a terminal and writes its transcript only to /dev/null.
+            // Both wrapper outputs pass through the redactor before reaching ours.
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        // A passthrough username carries no API key; the username itself is
+        // still redacted.
+        const separator = connection.PGUSER.indexOf('+');
+        const apiKey = separator === -1 ? '' : connection.PGUSER.slice(separator + 1);
+        const secrets = [connection.PGUSER, connection.PGPASSWORD, apiKey].filter(Boolean);
+        // The last output text, unredacted and never printed, kept only to
+        // recognise libpq's refusal of sslrootcert=system. script runs psql on a
+        // terminal, which merges psql's stderr into script's stdout, so both
+        // streams are watched.
+        let outputTail = '';
+        const watch = (chunk) => { outputTail = (outputTail + chunk.toString()).slice(-1024); };
+        child.stdout.on('data', watch);
+        child.stderr.on('data', watch);
+        const redact = (source, target) => {
+            let pending = '';
+            const scrub = (chunk, ending = false) => {
+                let output = '';
+                for (const character of chunk) {
+                    pending += character;
+                    while (pending) {
+                        const complete = secrets.find((secret) => pending.startsWith(secret));
+                        const possibleLonger = secrets.some((secret) => secret.length > pending.length && secret.startsWith(pending));
+                        if (possibleLonger)
+                            break;
+                        if (complete) {
+                            output += '[redacted]';
+                            pending = pending.slice(complete.length);
+                        }
+                        else {
+                            output += pending[0];
+                            pending = pending.slice(1);
+                        }
+                    }
+                }
+                if (ending && pending) {
+                    output += secrets.some((secret) => secret.startsWith(pending)) ? '[redacted]' : pending;
+                    pending = '';
+                }
+                if (output)
+                    target.write(output);
+            };
+            source.setEncoding('utf8');
+            source.on('data', (chunk) => scrub(chunk));
+            return () => scrub('', true);
+        };
+        const flushStdout = redact(child.stdout, process.stdout);
+        const flushStderr = redact(child.stderr, process.stderr);
+        const keepParentAlive = () => { };
+        const stopChild = () => { child.kill('SIGTERM'); };
+        process.on('SIGINT', keepParentAlive);
+        process.on('SIGTERM', stopChild);
+        process.on('SIGHUP', stopChild);
+        child.once('error', () => reject(new Error('Could not launch psql. Check that it is installed and on PATH.')));
+        child.once('close', (code, signal) => {
+            process.off('SIGINT', keepParentAlive);
+            process.off('SIGTERM', stopChild);
+            process.off('SIGHUP', stopChild);
+            flushStdout();
+            flushStderr();
+            if (code === 0)
+                resolve();
+            else if (libpqRefusedSystemRoots.test(outputTail))
+                reject(new Error(libpqTooOld('This psql\'s libpq')));
+            else
+                reject(new Error(signal ? `psql stopped after signal ${signal}.` : `psql exited with status ${code}.`));
+        });
+    });
+}

package/dist/branches/recovery.d.ts

@@ -0,0 +1,19 @@
+export interface CredentialRecovery {
+    file: string;
+    branchID: string;
+    requestID: string;
+    issuanceID?: string;
+    sourceRole?: string;
+}
+export declare class CredentialRecoveryCleanupError extends Error {
+    readonly stage: 'remove' | 'sync';
+    constructor(stage: 'remove' | 'sync', cause: unknown);
+}
+export declare function openCredentialWitness(requestID: string): Promise<{
+    port: number;
+    close: () => Promise<void>;
+}>;
+export declare function rememberCredentialRequest(directory: string, branchID: string, token: string, port: number, requestID: string, sourceRole?: string): Promise<CredentialRecovery>;
+export declare function rememberCredentialIssuance(recovery: CredentialRecovery, issuanceID: string): Promise<void>;
+export declare function forgetCredentialRecovery(recovery: CredentialRecovery): Promise<void>;
+export declare function recoverBranchCredentials(directory: string, token: string): Promise<number>;