@aifabrix/server-setup 0.1.0

package/dist/restore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Restore: unpack zip (backup.db + config + keys), push builder.db and keys to server DATA_DIR.
+ */
+import { type SSHConnectionOptions } from './ssh.js';
+export interface RestoreOptions extends SSHConnectionOptions {
+    zipPath: string;
+    dataDir?: string;
+    force?: boolean;
+}
+export interface RestoreLocalOptions {
+    zipPath: string;
+    dataDir?: string;
+    force?: boolean;
+}
+export declare function runRestore(options: RestoreOptions): Promise<void>;
+/** Run restore to local DATA_DIR (no SSH). Call requireUbuntu() before this. */
+export declare function runRestoreLocal(options: RestoreLocalOptions): Promise<void>;

package/dist/restore.js

@@ -0,0 +1,101 @@
+/**
+ * Restore: unpack zip (backup.db + config + keys), push builder.db and keys to server DATA_DIR.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
+import extract from 'extract-zip';
+import { createSSHClient, writeFile, exec, close } from './ssh.js';
+import { DATA_DIR_DEFAULT, BUILDER_DB, BACKUP_DB, CONFIG_JSON, KEY_FILES } from './config.js';
+export async function runRestore(options) {
+    const zipPath = path.resolve(process.cwd(), options.zipPath);
+    if (!fs.existsSync(zipPath)) {
+        throw new Error(`Zip not found: ${zipPath}`);
+    }
+    const tmpDir = path.join(process.cwd(), `.af-restore-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    try {
+        await extract(zipPath, { dir: tmpDir });
+        const configPath = path.join(tmpDir, CONFIG_JSON);
+        const backupDbPath = path.join(tmpDir, BACKUP_DB);
+        if (!fs.existsSync(configPath) || !fs.existsSync(backupDbPath)) {
+            throw new Error('Invalid backup zip: missing config.json or backup.db');
+        }
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const dataDir = options.dataDir ?? config.dataDir ?? DATA_DIR_DEFAULT;
+        const conn = await createSSHClient(options);
+        try {
+            await exec(conn, `mkdir -p ${dataDir}`);
+            if (!options.force) {
+                const check = await exec(conn, `test -f ${dataDir}/${BUILDER_DB} && echo exists || echo missing`);
+                if (check.stdout.trim() === 'exists') {
+                    throw new Error(`DATA_DIR already has ${BUILDER_DB}. Use --force to overwrite, or specify a different dataDir.`);
+                }
+            }
+            const dbBuf = fs.readFileSync(backupDbPath);
+            await writeFile(conn, `${dataDir}/${BUILDER_DB}`, dbBuf);
+            await exec(conn, `chmod 644 ${dataDir}/${BUILDER_DB}`);
+            await exec(conn, `chown 1001:65533 ${dataDir}/${BUILDER_DB}`);
+            for (const k of KEY_FILES) {
+                const localPath = path.join(tmpDir, k);
+                if (fs.existsSync(localPath)) {
+                    const buf = fs.readFileSync(localPath);
+                    await writeFile(conn, `${dataDir}/${k}`, buf);
+                    await exec(conn, `chmod 600 ${dataDir}/${k}`);
+                    await exec(conn, `chown 1001:65533 ${dataDir}/${k}`);
+                }
+            }
+            const restart = await exec(conn, 'docker restart builder-server 2>/dev/null || true');
+            if (restart.stderr && !restart.stderr.includes('No such container')) {
+                process.stderr.write(restart.stderr);
+            }
+        }
+        finally {
+            close(conn);
+        }
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** Run restore to local DATA_DIR (no SSH). Call requireUbuntu() before this. */
+export async function runRestoreLocal(options) {
+    const zipPath = path.resolve(process.cwd(), options.zipPath);
+    if (!fs.existsSync(zipPath)) {
+        throw new Error(`Zip not found: ${zipPath}`);
+    }
+    const tmpDir = path.join(process.cwd(), `.af-restore-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    try {
+        await extract(zipPath, { dir: tmpDir });
+        const configPath = path.join(tmpDir, CONFIG_JSON);
+        const backupDbPath = path.join(tmpDir, BACKUP_DB);
+        if (!fs.existsSync(configPath) || !fs.existsSync(backupDbPath)) {
+            throw new Error('Invalid backup zip: missing config.json or backup.db');
+        }
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const dataDir = options.dataDir ?? config.dataDir ?? DATA_DIR_DEFAULT;
+        fs.mkdirSync(dataDir, { recursive: true });
+        if (!options.force && fs.existsSync(path.join(dataDir, BUILDER_DB))) {
+            throw new Error(`DATA_DIR already has ${BUILDER_DB}. Use --force to overwrite, or specify a different dataDir.`);
+        }
+        const dbBuf = fs.readFileSync(backupDbPath);
+        fs.writeFileSync(path.join(dataDir, BUILDER_DB), dbBuf, { mode: 0o644 });
+        for (const k of KEY_FILES) {
+            const localPath = path.join(tmpDir, k);
+            if (fs.existsSync(localPath)) {
+                fs.copyFileSync(localPath, path.join(dataDir, k));
+                fs.chmodSync(path.join(dataDir, k), 0o600);
+            }
+        }
+        try {
+            execSync('docker restart builder-server 2>/dev/null || true', { stdio: 'inherit' });
+        }
+        catch {
+            // container may not exist
+        }
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}

package/dist/restore.spec.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for runRestore and runRestoreLocal (mocked SSH or no SSH).
+ */
+export {};

package/dist/restore.spec.js

@@ -0,0 +1,215 @@
+/**
+ * Tests for runRestore and runRestoreLocal (mocked SSH or no SSH).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import archiver from 'archiver';
+import Database from 'better-sqlite3';
+import { BACKUP_DB, CONFIG_JSON, KEY_FILES, BUILDER_DB } from './config.js';
+import { runRestore, runRestoreLocal } from './restore.js';
+const TEST_TMP_BASE = path.join(process.cwd(), 'tmp');
+const mockConn = {};
+const mockExec = jest.fn();
+const mockWriteFile = jest.fn();
+const mockClose = jest.fn();
+jest.mock('./ssh.js', () => ({
+    createSSHClient: jest.fn(() => Promise.resolve(mockConn)),
+    writeFile: jest.fn((...args) => mockWriteFile(...args)),
+    exec: jest.fn((...args) => mockExec(...args)),
+    close: jest.fn((...args) => mockClose(...args)),
+}));
+jest.mock('child_process', () => ({ execSync: jest.fn() }));
+describe('runRestore', () => {
+    let zipPath;
+    let workDir;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        fs.mkdirSync(TEST_TMP_BASE, { recursive: true });
+        workDir = fs.mkdtempSync(path.join(TEST_TMP_BASE, 'af-restore-'));
+        zipPath = path.join(workDir, 'backup.zip');
+        mockExec.mockResolvedValue({ stdout: '', stderr: '', code: 0 });
+        mockWriteFile.mockResolvedValue(undefined);
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(workDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('throws when zip not found', async () => {
+        await expect(runRestore({ target: 'user@host', zipPath: path.join(workDir, 'nonexistent.zip') })).rejects.toThrow('Zip not found');
+    });
+    it('unpacks zip and pushes builder.db and keys to server', async () => {
+        const zipContentDir = path.join(workDir, 'content');
+        fs.mkdirSync(zipContentDir, { recursive: true });
+        await new Promise((resolve, reject) => {
+            const dbPath = path.join(zipContentDir, BACKUP_DB);
+            const db = new Database(dbPath);
+            db.exec('CREATE TABLE users (id TEXT PRIMARY KEY);');
+            db.close();
+            fs.writeFileSync(path.join(zipContentDir, CONFIG_JSON), JSON.stringify({ dataDir: '/opt/data', createdAt: new Date().toISOString(), source: 'builder.db' }));
+            for (const k of KEY_FILES) {
+                fs.writeFileSync(path.join(zipContentDir, k), `content-${k}`);
+            }
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(zipPath);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.file(dbPath, { name: BACKUP_DB });
+            archive.file(path.join(zipContentDir, CONFIG_JSON), { name: CONFIG_JSON });
+            for (const k of KEY_FILES) {
+                archive.file(path.join(zipContentDir, k), { name: k });
+            }
+            archive.finalize();
+        });
+        await runRestore({ target: 'user@host', zipPath, force: true });
+        expect(mockWriteFile).toHaveBeenCalled();
+        expect(mockExec).toHaveBeenCalled();
+        expect(mockClose).toHaveBeenCalledWith(mockConn);
+    });
+    it('throws when zip missing config or backup.db', async () => {
+        const badZip = path.join(workDir, 'bad.zip');
+        await new Promise((resolve, reject) => {
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(badZip);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.append('dummy', { name: 'dummy.txt' });
+            archive.finalize();
+        });
+        await expect(runRestore({ target: 'user@host', zipPath: badZip })).rejects.toThrow('Invalid backup zip');
+    });
+    it('throws when builder.db exists on server and force not set', async () => {
+        const zipContentDir = path.join(workDir, 'content');
+        fs.mkdirSync(zipContentDir, { recursive: true });
+        const dbPath = path.join(zipContentDir, BACKUP_DB);
+        const db = new Database(dbPath);
+        db.exec('CREATE TABLE users (id TEXT PRIMARY KEY);');
+        db.close();
+        fs.writeFileSync(path.join(zipContentDir, CONFIG_JSON), JSON.stringify({ dataDir: '/opt/data', createdAt: new Date().toISOString(), source: 'builder.db' }));
+        await new Promise((resolve, reject) => {
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(zipPath);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.file(dbPath, { name: BACKUP_DB });
+            archive.file(path.join(zipContentDir, CONFIG_JSON), { name: CONFIG_JSON });
+            archive.finalize();
+        });
+        mockExec.mockImplementation((_conn, cmd) => {
+            if (cmd.includes('test -f') && cmd.includes('builder.db')) {
+                return Promise.resolve({ stdout: 'exists\n', stderr: '', code: 0 });
+            }
+            return Promise.resolve({ stdout: '', stderr: '', code: 0 });
+        });
+        await expect(runRestore({ target: 'user@host', zipPath })).rejects.toThrow('DATA_DIR already has builder.db');
+    });
+    it('writes docker restart stderr when not "No such container"', async () => {
+        const zipContentDir = path.join(workDir, 'content');
+        fs.mkdirSync(zipContentDir, { recursive: true });
+        const dbPath = path.join(zipContentDir, BACKUP_DB);
+        const db = new Database(dbPath);
+        db.exec('CREATE TABLE users (id TEXT PRIMARY KEY);');
+        db.close();
+        fs.writeFileSync(path.join(zipContentDir, CONFIG_JSON), JSON.stringify({ dataDir: '/opt/data', createdAt: new Date().toISOString(), source: 'builder.db' }));
+        await new Promise((resolve, reject) => {
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(zipPath);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.file(dbPath, { name: BACKUP_DB });
+            archive.file(path.join(zipContentDir, CONFIG_JSON), { name: CONFIG_JSON });
+            archive.finalize();
+        });
+        mockExec.mockImplementation((_conn, cmd) => {
+            if (cmd.includes('docker restart')) {
+                return Promise.resolve({ stdout: '', stderr: 'Error: something failed\n', code: 1 });
+            }
+            return Promise.resolve({ stdout: '', stderr: '', code: 0 });
+        });
+        const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runRestore({ target: 'user@host', zipPath, force: true });
+        expect(stderrSpy).toHaveBeenCalledWith('Error: something failed\n');
+        stderrSpy.mockRestore();
+    });
+});
+describe('runRestoreLocal', () => {
+    let workDir;
+    let zipPath;
+    beforeEach(() => {
+        fs.mkdirSync(TEST_TMP_BASE, { recursive: true });
+        workDir = fs.mkdtempSync(path.join(TEST_TMP_BASE, 'af-restore-local-'));
+        zipPath = path.join(workDir, 'backup.zip');
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(workDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it('throws when zip not found', async () => {
+        await expect(runRestoreLocal({ zipPath: path.join(workDir, 'nonexistent.zip') })).rejects.toThrow('Zip not found');
+    });
+    it('unpacks zip to local dataDir and writes builder.db and keys', async () => {
+        const zipContentDir = path.join(workDir, 'content');
+        fs.mkdirSync(zipContentDir, { recursive: true });
+        const dbPath = path.join(zipContentDir, BACKUP_DB);
+        const db = new Database(dbPath);
+        db.exec('CREATE TABLE users (id TEXT PRIMARY KEY); INSERT INTO users (id) VALUES (\'1\');');
+        db.close();
+        fs.writeFileSync(path.join(zipContentDir, CONFIG_JSON), JSON.stringify({ dataDir: '/opt/data', createdAt: new Date().toISOString(), source: 'builder.db' }));
+        for (const k of KEY_FILES) {
+            fs.writeFileSync(path.join(zipContentDir, k), `content-${k}`);
+        }
+        await new Promise((resolve, reject) => {
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(zipPath);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.file(dbPath, { name: BACKUP_DB });
+            archive.file(path.join(zipContentDir, CONFIG_JSON), { name: CONFIG_JSON });
+            for (const k of KEY_FILES) {
+                archive.file(path.join(zipContentDir, k), { name: k });
+            }
+            archive.finalize();
+        });
+        const dataDir = path.join(workDir, 'data');
+        await runRestoreLocal({ zipPath, dataDir, force: true });
+        expect(fs.existsSync(path.join(dataDir, BUILDER_DB))).toBe(true);
+        for (const k of KEY_FILES) {
+            expect(fs.readFileSync(path.join(dataDir, k), 'utf8')).toBe(`content-${k}`);
+        }
+    });
+    it('throws when builder.db exists and force not set', async () => {
+        const zipContentDir = path.join(workDir, 'content');
+        fs.mkdirSync(zipContentDir, { recursive: true });
+        const dbPath = path.join(zipContentDir, BACKUP_DB);
+        const db = new Database(dbPath);
+        db.exec('CREATE TABLE users (id TEXT PRIMARY KEY);');
+        db.close();
+        fs.writeFileSync(path.join(zipContentDir, CONFIG_JSON), JSON.stringify({ dataDir: '/opt/data', createdAt: new Date().toISOString(), source: 'builder.db' }));
+        await new Promise((resolve, reject) => {
+            const archive = archiver('zip', { zlib: { level: 6 } });
+            const out = fs.createWriteStream(zipPath);
+            out.on('close', () => resolve());
+            archive.on('error', reject);
+            archive.pipe(out);
+            archive.file(dbPath, { name: BACKUP_DB });
+            archive.file(path.join(zipContentDir, CONFIG_JSON), { name: CONFIG_JSON });
+            archive.finalize();
+        });
+        const dataDir = path.join(workDir, 'data');
+        fs.mkdirSync(dataDir, { recursive: true });
+        fs.writeFileSync(path.join(dataDir, BUILDER_DB), 'existing');
+        await expect(runRestoreLocal({ zipPath, dataDir })).rejects.toThrow('DATA_DIR already has builder.db');
+    });
+});

package/dist/ssh-cert.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SSH certificate commands for passwordless auth.
+ * request: obtain SSH cert (stub — requires builder-server or CA integration).
+ * install: append local SSH public key to server ~/.ssh/authorized_keys (or local when no target).
+ */
+import { type SSHConnectionOptions } from './ssh.js';
+export declare function runSshCertRequest(_options: SSHConnectionOptions & {
+    user?: string;
+}): Promise<void>;
+export declare function runSshCertInstall(options: SSHConnectionOptions): Promise<void>;
+/** Options for testing (inject homedir). */
+export interface RunSshCertInstallLocalOptions {
+    homedir?: string;
+}
+/**
+ * Append local default public key to local ~/.ssh/authorized_keys. Call after requireUbuntu().
+ */
+export declare function runSshCertInstallLocal(identityPath?: string, options?: RunSshCertInstallLocalOptions): void;

package/dist/ssh-cert.js

@@ -0,0 +1,92 @@
+/**
+ * SSH certificate commands for passwordless auth.
+ * request: obtain SSH cert (stub — requires builder-server or CA integration).
+ * install: append local SSH public key to server ~/.ssh/authorized_keys (or local when no target).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { createSSHClient, exec, readFile, writeFile, getRemoteHome, close } from './ssh.js';
+import { resolveLocalPublicKey } from './local-pubkey.js';
+const SSH_FX_NO_SUCH_FILE = 2;
+function authKeysPathLocal(homeOverride) {
+    return path.join(homeOverride ?? os.homedir(), '.ssh', 'authorized_keys');
+}
+function keyPartFromLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#'))
+        return null;
+    const parts = trimmed.split(/\s+/);
+    return parts[1] ?? null;
+}
+function keyAlreadyPresent(content, keyLine) {
+    const ourPart = keyPartFromLine(keyLine);
+    if (!ourPart)
+        return false;
+    const lines = content.split(/\r?\n/);
+    return lines.some((l) => keyPartFromLine(l) === ourPart);
+}
+export async function runSshCertRequest(_options) {
+    // Stub: would call builder-server API or local CA to sign user's public key.
+    console.log('ssh-cert request: not yet implemented. Requires SSH CA (e.g. builder-server or dedicated CA).');
+    console.log('Use af-server with key-based SSH (ssh-agent or -i key) for passwordless auth in the meantime.');
+}
+export async function runSshCertInstall(options) {
+    const keyLine = resolveLocalPublicKey(options.privateKeyPath).trim();
+    const conn = await createSSHClient(options);
+    try {
+        const home = await getRemoteHome(conn);
+        const sshDir = `${home}/.ssh`;
+        const authKeysPath = `${sshDir}/authorized_keys`;
+        await exec(conn, `mkdir -p "${sshDir.replace(/"/g, '\\"')}" && chmod 700 "${sshDir.replace(/"/g, '\\"')}"`);
+        let currentContent = '';
+        try {
+            const buf = await readFile(conn, authKeysPath);
+            currentContent = buf.toString('utf8');
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== SSH_FX_NO_SUCH_FILE) {
+                throw new Error('Could not read authorized_keys; check server permissions.');
+            }
+        }
+        if (keyAlreadyPresent(currentContent, keyLine)) {
+            console.log('Key already installed.');
+            return;
+        }
+        const date = new Date().toISOString().slice(0, 10);
+        const newLine = `${keyLine} # af-server ${date}\n`;
+        const newContent = currentContent + (currentContent && !currentContent.endsWith('\n') ? '\n' : '') + newLine;
+        await writeFile(conn, authKeysPath, newContent);
+        await exec(conn, `chmod 600 "${authKeysPath.replace(/"/g, '\\"')}"`);
+        console.log(`SSH key installed for ${options.target}. You can now run install/backup/restore without password (use this key or ssh-agent).`);
+    }
+    finally {
+        close(conn);
+    }
+}
+/**
+ * Append local default public key to local ~/.ssh/authorized_keys. Call after requireUbuntu().
+ */
+export function runSshCertInstallLocal(identityPath, options) {
+    const home = options?.homedir ?? os.homedir();
+    const keyLine = resolveLocalPublicKey(identityPath, { homedir: home }).trim();
+    const authKeysPath = authKeysPathLocal(home);
+    const sshDir = path.dirname(authKeysPath);
+    if (!fs.existsSync(sshDir)) {
+        fs.mkdirSync(sshDir, { mode: 0o700 });
+    }
+    let currentContent = '';
+    if (fs.existsSync(authKeysPath)) {
+        currentContent = fs.readFileSync(authKeysPath, 'utf8');
+    }
+    if (keyAlreadyPresent(currentContent, keyLine)) {
+        console.log('Key already installed.');
+        return;
+    }
+    const date = new Date().toISOString().slice(0, 10);
+    const newLine = `${keyLine} # af-server ${date}\n`;
+    const newContent = currentContent + (currentContent && !currentContent.endsWith('\n') ? '\n' : '') + newLine;
+    fs.writeFileSync(authKeysPath, newContent, { mode: 0o600 });
+    console.log('SSH key installed for local. You can now run install/backup/restore without password (use this key or ssh-agent).');
+}

package/dist/ssh-cert.spec.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for ssh-cert: request (stub), install (remote + local), and edge cases.
+ */
+export {};

package/dist/ssh-cert.spec.js

@@ -0,0 +1,101 @@
+/**
+ * Tests for ssh-cert: request (stub), install (remote + local), and edge cases.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { runSshCertRequest, runSshCertInstall, runSshCertInstallLocal } from './ssh-cert.js';
+const mockConn = {};
+const mockExec = jest.fn();
+const mockClose = jest.fn();
+const mockReadFile = jest.fn();
+const mockWriteFile = jest.fn();
+const mockGetRemoteHome = jest.fn();
+const KEY_LINE = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI test@local';
+jest.mock('./local-pubkey.js', () => ({
+    resolveLocalPublicKey: jest.fn(() => KEY_LINE),
+}));
+jest.mock('./ssh.js', () => ({
+    createSSHClient: jest.fn(() => Promise.resolve(mockConn)),
+    exec: jest.fn((...args) => mockExec(...args)),
+    readFile: jest.fn((...args) => mockReadFile(...args)),
+    writeFile: jest.fn((...args) => mockWriteFile(...args)),
+    getRemoteHome: jest.fn((...args) => mockGetRemoteHome(...args)),
+    close: jest.fn((...args) => mockClose(...args)),
+}));
+const TEST_TMP = path.join(process.cwd(), 'tmp', 'ssh-cert');
+describe('ssh-cert', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockExec.mockResolvedValue({ stdout: '/home/user', stderr: '', code: 0 });
+        mockGetRemoteHome.mockResolvedValue('/home/user');
+        mockReadFile.mockRejectedValue({ code: 2 }); // SSH_FX_NO_SUCH_FILE = no existing authorized_keys
+        mockWriteFile.mockResolvedValue(undefined);
+        jest.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        console.log.mockRestore();
+    });
+    describe('runSshCertRequest', () => {
+        it('runs without throwing and logs stub message', async () => {
+            await runSshCertRequest({ target: 'user@host' });
+            expect(console.log).toHaveBeenCalledWith(expect.stringContaining('ssh-cert request'));
+        });
+    });
+    describe('runSshCertInstall', () => {
+        it('resolves key, connects, ensures .ssh, appends key to authorized_keys, and prints success', async () => {
+            await runSshCertInstall({ target: 'user@host' });
+            expect(mockGetRemoteHome).toHaveBeenCalledWith(mockConn);
+            expect(mockExec).toHaveBeenCalled();
+            expect(mockReadFile).toHaveBeenCalled();
+            expect(mockWriteFile).toHaveBeenCalled();
+            expect(mockClose).toHaveBeenCalledWith(mockConn);
+            expect(console.log).toHaveBeenCalledWith(expect.stringContaining('SSH key installed for user@host'));
+        });
+        it('when key already present, does not write and logs "Key already installed."', async () => {
+            const existingContent = `${KEY_LINE}\n`;
+            mockReadFile.mockResolvedValueOnce(Buffer.from(existingContent, 'utf8'));
+            await runSshCertInstall({ target: 'user@host' });
+            expect(mockWriteFile).not.toHaveBeenCalled();
+            expect(console.log).toHaveBeenCalledWith('Key already installed.');
+            expect(mockClose).toHaveBeenCalledWith(mockConn);
+        });
+        it('throws actionable error when readFile fails with code other than NO_SUCH_FILE', async () => {
+            mockReadFile.mockRejectedValueOnce({ code: 3 }); // permission or other
+            await expect(runSshCertInstall({ target: 'user@host' })).rejects.toThrow('Could not read authorized_keys');
+            expect(mockClose).toHaveBeenCalledWith(mockConn);
+        });
+    });
+    describe('runSshCertInstallLocal', () => {
+        let fakeHome;
+        beforeEach(() => {
+            fs.mkdirSync(TEST_TMP, { recursive: true });
+            fakeHome = fs.mkdtempSync(path.join(TEST_TMP, 'home-'));
+        });
+        afterEach(() => {
+            try {
+                fs.rmSync(TEST_TMP, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        });
+        it('creates .ssh and authorized_keys and appends key with af-server comment', () => {
+            runSshCertInstallLocal(undefined, { homedir: fakeHome });
+            const authKeysPath = path.join(fakeHome, '.ssh', 'authorized_keys');
+            expect(fs.existsSync(authKeysPath)).toBe(true);
+            const content = fs.readFileSync(authKeysPath, 'utf8');
+            expect(content).toContain(KEY_LINE);
+            expect(content).toMatch(/# af-server \d{4}-\d{2}-\d{2}/);
+            expect(console.log).toHaveBeenCalledWith(expect.stringContaining('SSH key installed for local'));
+        });
+        it('when key already present, does not duplicate and logs "Key already installed."', () => {
+            runSshCertInstallLocal(undefined, { homedir: fakeHome });
+            const authKeysPath = path.join(fakeHome, '.ssh', 'authorized_keys');
+            const afterFirst = fs.readFileSync(authKeysPath, 'utf8');
+            runSshCertInstallLocal(undefined, { homedir: fakeHome });
+            const afterSecond = fs.readFileSync(authKeysPath, 'utf8');
+            expect(afterSecond).toBe(afterFirst);
+            expect(console.log).toHaveBeenCalledWith('Key already installed.');
+        });
+    });
+});

package/dist/ssh.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SSH client wrapper using ssh2. Used for install, backup, restore.
+ * Never log private keys or sensitive data.
+ */
+import { Client } from 'ssh2';
+export interface SSHConnectionOptions {
+    target: string;
+    privateKeyPath?: string;
+    privateKey?: string;
+    port?: number;
+}
+export declare function parseTarget(target: string): {
+    user: string;
+    host: string;
+};
+export declare function createSSHClient(options: SSHConnectionOptions): Promise<Client>;
+export declare function exec(conn: Client, command: string): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}>;
+/** Get remote user home directory (e.g. for ~/.ssh). Uses exec so paths work with SFTP. */
+export declare function getRemoteHome(conn: Client): Promise<string>;
+export declare function readFile(conn: Client, remotePath: string): Promise<Buffer>;
+export declare function writeFile(conn: Client, remotePath: string, data: Buffer | string): Promise<void>;
+export declare function mkdir(conn: Client, remotePath: string): Promise<void>;
+export declare function close(conn: Client): void;