@synopackageland/cli 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog
 
-## 0.32.0 (2026-10-27)
+## 0.33.0 (2026-10-27)
 
-- Attribute upstream Apps to their original project/team or owner and the packaging publisher as distributor, with generic skill guidance and a release checklist
-- Prefill upstream-fork attribution from the upstream repository and publisher options or environment configuration; use a bounded public GitHub owner lookup and explicit TODOs offline
-- Warn when upstream attribution is incomplete or the maintainer equals the distributor; warnings appear in check JSON and keep exit status successful
-- Keep templates 0.31.x and its SDK defaults; CLI minor releases can ship independently of templates
+- Share one secure NAS login across host, ctl, deploy, install, uninstall, status and logs
+- Install or upgrade store packages and local SPKs with dependency plans, compatibility checks and pinned download verification
+- Preview package changes with --dry-run, confirm with --yes and query installed packages without a project directory
+- Trust default NAS certificates on first use, pin the leaf SHA-256 before sending credentials and reject changed certificates until explicitly trusted
+- Distinguish certificate, DNS, connection refusal and timeout errors; support private CAs and expected certificate fingerprints
+- Document interactive and environment-only automation login without saving passwords

package/README.md

@@ -74,7 +74,7 @@ CLI-only releases can differ from the SDK patch. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.32.0 depends on `~0.31.0`: npm installation or
+`@synopackageland/templates`. CLI 0.32.1 depends on `~0.31.0`: npm installation or
 update can select the latest templates patch in the 0.31 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
@@ -346,11 +346,11 @@ DSM readiness; inspect lists explicit acceptance blockers.
 
 ## Control installed Apps
 
-Use `synopkgland ctl host add nas --url https://nas.example:5001 --username alice`
+Use `synopkgland host add nas --url https://nas.example:5001 --username alice`
 to register and authenticate a NAS in OS secure storage. A bare host name uses
 `https://<host>:5001`; provide a full URL for a different scheme or port.
 The CLI loads only `DSM_*` and `SYNOPKGLAND_*` variables from `.env`; set other
-process variables in the shell. `ctl host list --json`
+process variables in the shell. `host list --json`
 checks sessions; `ctl list --host nas --json` discovers all approved task-level
 commands and their schemas. Run the listed alias/command with typed flags,
 `--help` and `--dry-run`; writes require `--yes`. There is no mutable current
@@ -382,7 +382,7 @@ not become process exit codes 4 or 5. Attempting to execute an excluded App with
 `--refresh` instead returns `ok:false`, `CTL_APP_UNKNOWN` and exit 3 because the
 App is absent from discovery results; no business operation runs.
 
-`ctl host list/show` can also succeed while reporting `authenticated:false` and
+`host list/show` can also succeed while reporting `authenticated:false` and
 exit 0. Check discovery `apps`/`diagnostics` and session fields as well as the exit
 code when deciding whether an App is ready.
 `ctl --timeout <seconds>` applies to discovery, JSON calls, polling and transfer

package/dist/cli.js

@@ -289,6 +289,11 @@ async function containerBuild(project, arches, options) {
 }
 /** Resolves after dispatch; commands may set process.exitCode. Rejections are failures. */
 export async function runCli(argv) {
+    if (argv[2] === "host") {
+        const { runCtl } = await import("./ctl/cli.js");
+        await runCtl(["host", ...argv.slice(3)]);
+        return;
+    }
     if (argv[2] === "ctl") {
         const { runCtl } = await import("./ctl/cli.js");
         await runCtl(argv.slice(3));
@@ -304,14 +309,24 @@ export async function runCli(argv) {
         .option("--project <dir>", "App project root")
         .exitOverride();
     const rootOf = (command) => resolve(process.cwd(), command.parent?.opts().project ?? ".");
-    const hostOf = (host) => {
-        if (!host)
-            throw failure("HOST_REQUIRED", "--host is required.", "Set a synoagentcli profile, then use --host <name>.");
-        const nas = createNasHost({ host });
-        if (!nas)
-            throw failure("NAS_CREDENTIALS_MISSING", "NAS credentials were not found.", "Set a synoagentcli profile or DSM_URL/DSM_PASSWORD.");
-        return nas;
-    };
+    const hostOf = (host) => createNasHost({ host });
+    program.command("host").description("Shared NAS login and host management (host --help)");
+    program.command("install <package-or-spk>")
+        .description("Install a store package or a local SPK")
+        .option("--host <name>", "Registered NAS host")
+        .option("--source <url>", "HTTPS package source")
+        .option("--param <NAME=value>", "Install wizard value", (v, p) => collectKv(v, p, "--param"))
+        .option("--yes", "Confirm installation")
+        .option("--dry-run", "Print the installation plan without writing to DSM")
+        .option("--json", "Print a single JSON object")
+        .action(async (spec, options) => { const { installPackage } = await import('./host/package-commands.js'); const result = await installPackage(spec, options); emit('install', result, JSON.stringify(result, null, 2)); });
+    program.command("uninstall <package-id>")
+        .description("Remove an installed package")
+        .option("--host <name>", "Registered NAS host")
+        .option("--yes", "Confirm removal")
+        .option("--dry-run", "Print the removal plan without writing to DSM")
+        .option("--json", "Print a single JSON object")
+        .action(async (id, options) => { const { uninstallPackage } = await import('./host/package-commands.js'); const result = await uninstallPackage(id, options); emit('uninstall', result, JSON.stringify(result, null, 2)); });
     program.command("ctl").description("Control registered NAS Apps using described AI commands (ctl --help)");
     program
         .command("check")
@@ -473,7 +488,7 @@ export async function runCli(argv) {
         const targetDir = resolve(dir);
         const upstream = options.upstreamFork ? upstreamRepository(targetDir, options.upstream) : undefined;
         if (options.upstream && !upstream)
-            throw failure("INIT_UPSTREAM_INVALID", "Supply an http(s) repository URL without credentials");
+            throw failure("INIT_UPSTREAM_INVALID", "Supply an HTTPS repository URL without credentials");
         if (!options.upstreamFork && (options.upstream || options.upstreamMaintainer || options.publisher || options.publisherUrl))
             throw failure("INIT_OPTIONS_UNSUPPORTED", "Attribution options require --upstream-fork");
         initFromTemplate(options.template, targetDir, {
@@ -608,12 +623,18 @@ export async function runCli(argv) {
         emit("deploy", result, `Deployed ${result.packageId}${result.openUrl ? "\nOpen URL: " + result.openUrl : ""}`);
     });
     program
-        .command("status")
+        .command("status [package-id]")
         .description("DSM package status, Open URL and capability readiness")
         .option("--json", "Print a single JSON object")
         .option("--host <name>", "NAS profile")
         .option("--dev", "Development Package Identity")
-        .action(async (options, command) => {
+        .action(async (id, options, command) => {
+        if (id) {
+            const { packageStatus } = await import('./host/package-commands.js');
+            const result = await packageStatus(id, options.host);
+            emit('status', result, JSON.stringify(result, null, 2));
+            return;
+        }
         const host = hostOf(options.host);
         const root = rootOf(command);
         const standalone = standaloneRoot(root);
@@ -629,7 +650,7 @@ export async function runCli(argv) {
     program
         .command("logs")
         .description("Status diagnosis: DSM package status and masked diagnostics; does not stream application logs")
-        .requiredOption("--host <name>", "NAS profile")
+        .option("--host <name>", "Registered NAS host")
         .option("--dev", "Development Package Identity")
         .action(async (options, command) => {
         const host = hostOf(options.host);

package/dist/ctl/cli.d.ts

@@ -4,6 +4,7 @@ import type { Descriptor } from './descriptor.js';
 export interface CtlIO {
     store?: CtlStore;
     out?: (line: string) => void;
+    err?: (line: string) => void;
     isTTY?: boolean;
     prompt?: (message: string, secret?: boolean) => Promise<string>;
     requestFor?: (host: Host) => JsonRequest;

package/dist/ctl/cli.js

@@ -1,3 +1,4 @@
+import { probeCertificate, normalizeFingerprint } from './tls.js';
 import { readBounded } from './json.js';
 import { readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
@@ -9,7 +10,7 @@ import { selectHosts, selectApp, selectOperation, flagName, RESERVED_FLAGS } fro
 import { canonicalOrigin, CTL_TIMEOUT_MS, createRequest } from './transport.js';
 import { loginDsm, logoutDsm } from './dsm-auth.js';
 import { publicOperation } from './redaction.js';
-const USAGE = 'synopkgland ctl host add|list|show|login|logout|remove|revoke; ctl list [--host a,b|--all-hosts] [--app pkg] [--refresh]; ctl <alias|package> <command...> [typed flags|--input file|-] [--dry-run] [--yes]';
+const USAGE = 'synopkgland host add|list|show|login|logout|remove|revoke|default|trust; ctl list [--host a,b|--all-hosts] [--app pkg] [--refresh]; ctl <alias|package> <command...> [typed flags|--input file|-] [--dry-run] [--yes]';
 async function prompt(message, secret = false) {
     if (!process.stdin.isTTY)
         throw new CtlError('CTL_INTERACTION_REQUIRED', 'Interactive input required.', 'Use --username and --password-stdin for host authentication.', 2);
@@ -79,7 +80,7 @@ export async function runCtl(argv, io = {}) {
         if (args[0] === 'host') {
             const action = args[1], name = args[2];
             if (help || !action) {
-                emit({ ok: true, data: { usage: USAGE, actions: ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke'] } });
+                emit({ ok: true, data: { usage: USAGE, actions: ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke', 'default', 'trust'] } });
                 return;
             }
             if (action === 'list') {
@@ -88,31 +89,55 @@ export async function runCtl(argv, io = {}) {
                 return;
             }
             if (!name)
-                throw new CtlError('CTL_ARGUMENT_INVALID', 'Host name is required.', 'run: synopkgland ctl host list');
+                throw new CtlError('CTL_ARGUMENT_INVALID', 'Host name is required.', 'run: synopkgland host list');
+            if (action === 'default') {
+                store.setDefault(name);
+                emit({ ok: true, data: { defaultHost: name } });
+                return;
+            }
             if (action === 'add' || action === 'login') {
                 const remaining = args.slice(3);
-                const url = take(remaining, '--url', true), usernameOption = take(remaining, '--username', true), passwordStdin = !!take(remaining, '--password-stdin'), tunnel = !!take(remaining, '--ssh-tunnel'), noRemember = !!take(remaining, '--no-remember-device'), ca = take(remaining, '--ca', true);
+                const url = take(remaining, '--url', true), usernameOption = take(remaining, '--username', true), passwordStdin = !!take(remaining, '--password-stdin'), tunnel = !!take(remaining, '--ssh-tunnel'), noRemember = !!take(remaining, '--no-remember-device'), ca = take(remaining, '--ca', true), fingerprint = take(remaining, '--fingerprint', true);
+                if (ca && fingerprint)
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Use --ca or --fingerprint', 'Choose one certificate trust policy');
                 if (remaining.length)
-                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Unknown host options.', 'run: synopkgland ctl host --help', 3, remaining);
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Unknown host options.', 'run: synopkgland host --help', 3);
                 if (action === 'add' && store.list().some(h => h.name === name))
-                    throw new CtlError('CTL_HOST_EXISTS', `Host ${name} already registered.`, `run: synopkgland ctl host login ${name}`);
+                    throw new CtlError('CTL_HOST_EXISTS', `Host ${name} already registered.`, `run: synopkgland host login ${name}`);
                 if (action === 'login' && (url || usernameOption || tunnel || ca))
-                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Login uses the registered URL/account; add a separately named host to change them.', `run: synopkgland ctl host show ${name}`);
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Login uses the registered URL/account; add a separately named host to change them.', `run: synopkgland host show ${name}`);
                 const old = action === 'login' ? store.get(name) : undefined;
                 if (action === 'add' && !url)
-                    throw new CtlError('CTL_URL_REQUIRED', '--url is required.', `run: synopkgland ctl host add ${name} --url https://${name}:5001`);
-                const host = old ?? { name, origin: canonicalOrigin(url, tunnel), username: usernameOption ?? await ask('DSM account: '), approved: {}, ...(tunnel ? { tunnel: true } : {}), ...(ca ? { ca } : {}) };
+                    throw new CtlError('CTL_URL_REQUIRED', '--url is required.', `run: synopkgland host add ${name} --url https://${name}:5001`);
+                const host = old ?? { name, origin: canonicalOrigin(url, tunnel), username: usernameOption ?? process.env.DSM_USERNAME ?? await ask('DSM account: '), approved: {}, ...(tunnel ? { tunnel: true } : {}), ...(ca ? { ca } : {}) };
+                if (fingerprint)
+                    normalizeFingerprint(fingerprint);
+                if (old?.fingerprint && fingerprint && normalizeFingerprint(fingerprint) !== old.fingerprint)
+                    throw new CtlError('HOST_CERT_CHANGED', 'Login cannot replace a certificate pin', `run: synopkgland host trust ${name}`, 6);
+                if (!io.requestFor) {
+                    const checked = await probeCertificate(host.origin, { name, ca: host.ca ? readFileSync(host.ca, 'utf8') : undefined, fingerprint: host.fingerprint ?? fingerprint, timeoutMs });
+                    if (checked.fingerprint && !host.fingerprint) {
+                        host.fingerprint = checked.fingerprint;
+                        store.save(host);
+                        if (!checked.trusted)
+                            (io.err ?? console.error)(`Trusting the NAS certificate ${checked.fingerprint.slice(0, 16)} (self-signed)`);
+                    }
+                }
+                else if (fingerprint)
+                    host.fingerprint = normalizeFingerprint(fingerprint);
                 const previous = old ? await store.credentials.get(store.key(host)) : null;
-                const secret = passwordStdin ? readBounded(0, 4096).replace(/[\r\n]+$/, '') : await ask('User password: ', true);
-                const session = await loginDsm(host.origin, host.username, secret, { remember: !noRemember, deviceId: previous?.deviceId, otp: () => ask('DSM OTP: ', true), request: io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs, host.ca ? readFileSync(host.ca, 'utf8') : undefined), ca: host.ca ? readFileSync(host.ca, 'utf8') : undefined });
+                const secret = process.env.DSM_PASSWORD ?? (passwordStdin ? readBounded(0, 4096).replace(/[\r\n]+$/, '') : await ask('User password: ', true));
+                const session = await loginDsm(host.origin, host.username, secret, { remember: !noRemember, deviceId: previous?.deviceId, otp: () => process.env.DSM_OTP ? Promise.resolve(process.env.DSM_OTP) : ask('DSM OTP: ', true), request: io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs, host.ca ? readFileSync(host.ca, 'utf8') : undefined, { fingerprint: host.fingerprint, name: host.name }), ca: host.ca ? readFileSync(host.ca, 'utf8') : undefined });
                 try {
-                    if (old)
+                    if (old || host.fingerprint) {
                         await store.credentials.set(store.key(host), session);
+                        store.save(host);
+                    }
                     else
                         await store.add(host, session);
                 }
                 catch (e) {
-                    await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs)).catch(() => { });
+                    await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs, host.ca ? readFileSync(host.ca, 'utf8') : undefined, { fingerprint: host.fingerprint, name: host.name })).catch(() => { });
                     throw e;
                 }
                 host.lastUsed = new Date().toISOString();
@@ -121,25 +146,42 @@ export async function runCtl(argv, io = {}) {
                 return;
             }
             const host = store.get(name);
+            if (action === 'trust') {
+                if (host.ca)
+                    throw new CtlError('HOST_CA_CONFIGURED', 'This host uses a configured CA', 'Update the trusted CA file instead of replacing it with a leaf pin', 3);
+                if (!host.origin.startsWith('https:'))
+                    throw new CtlError('HOST_TLS_REQUIRED', 'Certificate trust requires HTTPS', 'Use an HTTPS host registration', 3);
+                const checked = await probeCertificate(host.origin, { fingerprint: take(args, '--fingerprint', true), name });
+                // Get the leaf even when system-trusted, to make an explicit re-pin stable.
+                const current = checked.leafFingerprint;
+                if (!current)
+                    throw new CtlError('HOST_TLS_SYSTEM_TRUSTED', 'This NAS certificate is trusted by the system', 'Remove the old pin only after verifying the NAS certificate with --fingerprint', 3);
+                if (!yes && (!tty || !/^y(es)?$/i.test(await ask(`Trust NAS certificate SHA-256 ${current} (previous ${host.fingerprint ?? 'none'})? [y/N] `))))
+                    throw new CtlError('HOST_TRUST_CONFIRM_REQUIRED', 'Certificate replacement requires confirmation', `Verify the certificate, then run: synopkgland host trust ${name}`, 7);
+                host.fingerprint = current;
+                store.save(host);
+                emit({ ok: true, data: { name, fingerprint: current } });
+                return;
+            }
             if (action === 'show') {
                 emit({ ok: true, data: { ...host, authenticated: await client(host).valid() } });
                 return;
             }
             if (action === 'revoke') {
                 if (!args[3])
-                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Package ID is required.', `run: synopkgland ctl host show ${name}`);
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Package ID is required.', `run: synopkgland host show ${name}`);
                 emit({ ok: true, data: store.revoke(name, args[3]) });
                 return;
             }
             if (action === 'logout' || action === 'remove') {
                 if (action === 'remove' && !yes && (!tty || !/^y(es)?$/i.test(await ask(`Remove all local data for ${name}? [y/N] `))))
-                    throw new CtlError('CTL_CONFIRM_REQUIRED', 'Host removal requires --yes.', `run: synopkgland ctl host remove ${name} --yes`, 7);
+                    throw new CtlError('CTL_CONFIRM_REQUIRED', 'Host removal requires --yes.', `run: synopkgland host remove ${name} --yes`, 7);
                 const session = await store.credentials.get(store.key(host));
                 let loggedOut = false;
                 let logoutError;
                 if (session?.cookie) {
                     try {
-                        await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs, host.ca ? readFileSync(host.ca, 'utf8') : undefined));
+                        await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin, timeoutMs, host.ca ? readFileSync(host.ca, 'utf8') : undefined, { fingerprint: host.fingerprint, name: host.name }));
                         loggedOut = true;
                     }
                     catch (error) {
@@ -151,15 +193,15 @@ export async function runCtl(argv, io = {}) {
                     return;
                 }
                 if (logoutError)
-                    throw new CtlError('CTL_LOGOUT_FAILED', 'DSM logout was not confirmed; local session retained for retry.', `run: synopkgland ctl host logout ${name}`, 6);
+                    throw new CtlError('CTL_LOGOUT_FAILED', 'DSM logout was not confirmed; local session retained for retry.', `run: synopkgland host logout ${name}`, 6);
                 if (session)
                     await store.credentials.set(store.key(host), { ...session, cookie: '', token: '' });
                 emit({ ok: true, data: { name, loggedOut, registrationRetained: true } });
                 return;
             }
-            throw new CtlError('CTL_COMMAND_UNKNOWN', `Unknown host action ${action}.`, 'run: synopkgland ctl host --help', 3, ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke']);
+            throw new CtlError('CTL_COMMAND_UNKNOWN', `Unknown host action ${action}.`, 'run: synopkgland host --help', 3, ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke', 'default', 'trust']);
         }
-        const names = selectHosts(store.list().map(h => h.name), hostOption, allHosts);
+        const names = selectHosts(store.list().map(h => h.name), hostOption ?? (allHosts ? undefined : store.defaultName()), allHosts);
         const inputAt = args.indexOf('--input');
         let commonInput;
         if (inputAt >= 0 && args[inputAt + 1] === '-') {

package/dist/ctl/dsm-auth.js

@@ -11,12 +11,12 @@ export async function loginDsm(origin, username, password, options) {
     if (result?.error?.code === 403) {
         const otp = await options.otp();
         if (!/^\d{6}$/.test(otp))
-            throw new CtlError('CTL_OTP_INVALID', 'OTP must be six digits.', 'run: synopkgland ctl host login <name>', 2);
+            throw new CtlError('CTL_OTP_INVALID', 'OTP must be six digits.', 'run: synopkgland host login <name>', 2);
         form.set('otp_code', otp);
         result = await request('/webapi/entry.cgi', form);
     }
     if (result?.success !== true || typeof result.data?.sid !== 'string' || !result.data.sid || typeof result.data.synotoken !== 'string' || !result.data.synotoken)
-        throw new CtlError('CTL_AUTH_FAILED', `DSM login failed (${Number(result?.error?.code) || 'invalid response'}).`, 'run: synopkgland ctl host login <name>', 2);
+        throw new CtlError('CTL_AUTH_FAILED', `DSM login failed (${Number(result?.error?.code) || 'invalid response'}).`, 'run: synopkgland host login <name>', 2);
     if (/[;\r\n\x00]/.test(result.data.sid) || /[\r\n\x00]/.test(result.data.synotoken) || result.data.sid.length > 4096 || result.data.synotoken.length > 4096)
         throw new CtlError('CTL_AUTH_FAILED', 'DSM returned invalid session carriers.', 'Check the DSM endpoint.', 2);
     const returnedDevice = result.data.device_id || result.data.did || options.deviceId;

package/dist/ctl/errors.js

@@ -28,5 +28,5 @@ export function choose(value, allowed, what) {
         row = next;
     } return row[b.length]; };
     const nearest = [...allowed].sort((a, b) => distance(value.toLowerCase(), a.toLowerCase()) - distance(value.toLowerCase(), b.toLowerCase()))[0];
-    throw new CtlError(`CTL_${what.toUpperCase()}_UNKNOWN`, `Unknown ${what}: ${value}.${nearest ? ` Did you mean ${nearest}?` : ''}`, nearest ? `run: synopkgland ctl ${what === 'host' ? `host show ${nearest}` : 'list --json'}` : 'run: synopkgland ctl host add <name> --url https://<nas>:5001', 3, allowed);
+    throw new CtlError(`CTL_${what.toUpperCase()}_UNKNOWN`, `Unknown ${what}: ${value}.${nearest ? ` Did you mean ${nearest}?` : ''}`, nearest ? `run: synopkgland ctl ${what === 'host' ? `host show ${nearest}` : 'list --json'}` : 'run: synopkgland host add <name> --url https://<nas>:5001', 3, allowed);
 }

package/dist/ctl/input.js

@@ -4,9 +4,9 @@ import { CtlError, choose } from './errors.js';
 import { redactValue } from './redaction.js';
 export function selectHosts(names, selected, all = false) {
     if (selected && all)
-        throw new CtlError('CTL_ARGUMENT_INVALID', 'Use --host or --all-hosts, not both.', 'run: synopkgland ctl host list');
+        throw new CtlError('CTL_ARGUMENT_INVALID', 'Use --host or --all-hosts, not both.', 'run: synopkgland host list');
     if (!names.length)
-        throw new CtlError('CTL_NOT_AUTHENTICATED', 'No hosts registered.', 'run: synopkgland ctl host add <name> --url https://<nas>:5001', 2);
+        throw new CtlError('CTL_NOT_AUTHENTICATED', 'No hosts registered.', 'run: synopkgland host add <name> --url https://<nas>:5001', 2);
     if (all)
         return names;
     if (!selected) {

package/dist/ctl/service.js

@@ -17,7 +17,7 @@ export class CtlClient {
     constructor(store, host, request, timeoutMs = CTL_TIMEOUT_MS) {
         this.store = store;
         this.host = host;
-        this.request = request ?? createRequest(host.origin, () => this.remaining(timeoutMs), host.ca ? readFileSync(host.ca, 'utf8') : undefined);
+        this.request = request ?? createRequest(host.origin, () => this.remaining(timeoutMs), host.ca ? readFileSync(host.ca, 'utf8') : undefined, { fingerprint: host.fingerprint, name: host.name });
     }
     until;
     remaining(fallback) { return this.until === undefined ? fallback : Math.max(0, this.until - performance.now()); }
@@ -25,14 +25,16 @@ export class CtlClient {
         await this.inventory(await this.store.session(this.host));
         return true;
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError && error.code.startsWith('HOST_'))
+            throw error;
         return false;
     } }
     async inventory(session) {
         const response = await this.request('/webapi/entry.cgi', new URLSearchParams({ api: 'SYNO.Core.Package', version: '2', method: 'list', additional: '["status"]', SynoToken: session.token }), session);
         if (response?.success !== true) {
             const code = Number(response?.error?.code);
-            throw new CtlError([106, 107, 119].includes(code) ? 'CTL_NOT_AUTHENTICATED' : 'CTL_INVENTORY_DENIED', `DSM Package list failed (${code}).`, `run: synopkgland ctl host login ${this.host.name}`, [106, 107, 119].includes(code) ? 2 : 4);
+            throw new CtlError([106, 107, 119].includes(code) ? 'CTL_NOT_AUTHENTICATED' : 'CTL_INVENTORY_DENIED', `DSM Package list failed (${code}).`, `run: synopkgland host login ${this.host.name}`, [106, 107, 119].includes(code) ? 2 : 4);
         }
         const entries = response.data?.packages;
         if (!Array.isArray(entries) || response.data.total !== entries.length || entries.length > 4096)
@@ -134,7 +136,7 @@ export class CtlClient {
                 const boot = await this.request(app.payload.transport.path, { method: 'identity.session', params: { bootstrap: true } }, session);
                 // The transport adapter adds only validated, path-scoped App cookies for this call.
                 if (boot?.success !== true)
-                    throw new CtlError('CTL_APP_SESSION', 'App session bootstrap failed; HTTPS is required.', `run: synopkgland ctl host show ${this.host.name}`, 5);
+                    throw new CtlError('CTL_APP_SESSION', 'App session bootstrap failed; HTTPS is required.', `run: synopkgland host show ${this.host.name}`, 5);
                 appSession = this.appCookieSession(session, boot);
             }
             try {
@@ -150,8 +152,8 @@ export class CtlClient {
                 };
                 const ca = this.host.ca ? readFileSync(this.host.ca, 'utf8') : undefined;
                 const result = await runFlow(operation.flow, params, invoke, { wait: options.wait, timeoutMs: this.remaining(options.timeoutMs ?? CTL_TIMEOUT_MS),
-                    ndjson: (method, input) => transferRequest(appSession, app.payload.transport.path, method, input, { ca, timeoutMs: this.remaining(options.timeoutMs ?? CTL_TIMEOUT_MS) }),
-                    upload: (method, input, flow) => transferRequest(appSession, app.payload.transport.path, method, {}, { ca, timeoutMs: this.remaining(options.timeoutMs ?? CTL_TIMEOUT_MS), file: { path: String(input[flow.fileParam]), parent: String(input[flow.parentParam]), name: String(input[flow.nameParam]) } }) });
+                    ndjson: (method, input) => transferRequest(appSession, app.payload.transport.path, method, input, { ca, trust: { fingerprint: this.host.fingerprint, name: this.host.name }, timeoutMs: this.remaining(options.timeoutMs ?? CTL_TIMEOUT_MS) }),
+                    upload: (method, input, flow) => transferRequest(appSession, app.payload.transport.path, method, {}, { ca, trust: { fingerprint: this.host.fingerprint, name: this.host.name }, timeoutMs: this.remaining(options.timeoutMs ?? CTL_TIMEOUT_MS), file: { path: String(input[flow.fileParam]), parent: String(input[flow.parentParam]), name: String(input[flow.nameParam]) } }) });
                 if (operation.resultSchema && !ajv.validate(operation.resultSchema, result))
                     throw new CtlError('CTL_RESPONSE_INVALID', 'Result does not match command schema.', 'Check the App version.', 5);
                 return output.clean(result, operation.resultSchema);

package/dist/ctl/store.d.ts

@@ -7,6 +7,7 @@ export interface Host {
     name: string;
     origin: string;
     username: string;
+    fingerprint?: string;
     tunnel?: boolean;
     ca?: string;
     lastUsed?: string;
@@ -30,6 +31,9 @@ export declare class CtlStore {
     private safe;
     private file;
     key(host: Host): string;
+    defaultName(): string | undefined;
+    setDefault(name: string): void;
+    select(name?: string): Host;
     list(): Host[];
     get(name: string): Host;
     save(host: Host): void;

package/dist/ctl/store.js

@@ -3,6 +3,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { CtlError, choose } from './errors.js';
+import { loginDsm } from './dsm-auth.js';
+import { createRequest } from './transport.js';
 import { publicDescriptor } from './redaction.js';
 export class OsCredentialStore {
     async entry(key) { try {
@@ -45,22 +47,47 @@ export class CtlStore {
         throw new CtlError('CTL_HOST_INVALID', 'Invalid host name.', 'Use letters, digits, dots, dashes or underscores.'); return name; }
     file(name) { return join(this.root, 'hosts', this.safe(name) + '.json'); }
     key(host) { return createHash('sha256').update(host.name + '\0' + host.origin + '\0' + host.username).digest('hex'); }
+    defaultName() { try {
+        return JSON.parse(readFileSync(join(this.root, 'default.json'), 'utf8')).name;
+    }
+    catch {
+        return undefined;
+    } }
+    setDefault(name) { this.get(name); mkdirSync(this.root, { recursive: true, mode: 0o700 }); const file = join(this.root, 'default.json'), temp = file + '.' + randomUUID(); writeFileSync(temp, JSON.stringify({ name }), { mode: 0o600 }); renameSync(temp, file); }
+    select(name) { if (name)
+        return this.get(name); const hosts = this.list(); const selected = this.defaultName(); if (selected)
+        return this.get(selected); if (hosts.length === 1)
+        return hosts[0]; throw new CtlError('CTL_HOST_REQUIRED', hosts.length ? 'Choose a NAS with --host.' : 'No NAS hosts registered.', hosts.length ? 'run: synopkgland host default <name>' : 'run: synopkgland host add <name> --url https://<nas>:5001', 2); }
     list() { const dir = join(this.root, 'hosts'); if (!existsSync(dir))
         return []; return readdirSync(dir).filter(n => n.endsWith('.json')).map(n => JSON.parse(readFileSync(join(dir, n), 'utf8'))).sort((a, b) => a.name.localeCompare(b.name)); }
     get(name) { this.safe(name); const host = this.list().find(h => h.name === name); if (!host)
         return choose(name, this.list().map(h => h.name), 'host'); return host; }
     save(host) { const file = this.file(host.name); mkdirSync(join(this.root, 'hosts'), { recursive: true, mode: 0o700 }); const temp = file + '.' + randomUUID(); writeFileSync(temp, JSON.stringify(host), { mode: 0o600 }); renameSync(temp, file); chmodSync(file, 0o600); }
     async add(host, session) { if (this.list().some(h => h.name === host.name))
-        throw new CtlError('CTL_HOST_EXISTS', 'Host name already registered.', `run: synopkgland ctl host login ${host.name}`); await this.credentials.set(this.key(host), session); try {
+        throw new CtlError('CTL_HOST_EXISTS', 'Host name already registered.', `run: synopkgland host login ${host.name}`); await this.credentials.set(this.key(host), session); try {
         this.save(host);
     }
     catch (e) {
         await this.credentials.delete(this.key(host));
         throw e;
     } }
-    async session(host) { const session = await this.credentials.get(this.key(host)); if (!session?.cookie || !session.token)
-        throw new CtlError('CTL_NOT_AUTHENTICATED', `Host ${host.name} is not logged in.`, `run: synopkgland ctl host login ${host.name}`, 2); if (session.origin !== host.origin || session.username !== host.username)
-        throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Stored credentials do not match host.', 'Run ctl host login again.', 2); return session; }
+    async session(host) {
+        let session;
+        if (process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
+            if (process.env.DSM_USERNAME !== host.username)
+                throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Automation account differs from the registered host.', 'Use the registered account or a separately named host.', 2);
+            session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, 30000, host.ca ? readFileSync(host.ca, 'utf8') : undefined, { fingerprint: host.fingerprint, name: host.name }) });
+        }
+        else
+            session = await this.credentials.get(this.key(host));
+        if (!session?.cookie || !session.token)
+            throw new CtlError('CTL_NOT_AUTHENTICATED', `Host ${host.name} is not logged in.`, `run: synopkgland host login ${host.name}`, 2);
+        if (/[\r\n\0]/.test(session.cookie + session.token))
+            throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Stored session carriers are invalid', `run: synopkgland host login ${host.name}`, 2);
+        if (session.origin !== host.origin || session.username !== host.username)
+            throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Stored credentials do not match host.', 'Run synopkgland host login again.', 2);
+        return session;
+    }
     cacheRoot(host) { return join(this.root, 'cache', this.key(host)); }
     cacheFile(host, pkg, version) { return join(this.cacheRoot(host), createHash('sha256').update(pkg + '\0' + version).digest('hex') + '.json'); }
     cache(host, pkg, version) {
@@ -89,5 +116,6 @@ export class CtlStore {
     }
     putFailure(host, pkg, version, failure) { mkdirSync(this.cacheRoot(host), { recursive: true, mode: 0o700 }); const file = this.cacheFile(host, pkg, version), tmp = file + '.' + randomUUID(); writeFileSync(tmp, JSON.stringify({ failure }), { mode: 0o600 }); renameSync(tmp, file); }
     revoke(name, pkg) { const host = this.get(name); delete host.approved[pkg]; this.save(host); rmSync(this.cacheRoot(host), { recursive: true, force: true }); return { revoked: pkg, cacheCleared: true }; }
-    async remove(name) { const host = this.get(name); await this.credentials.delete(this.key(host)); rmSync(this.cacheRoot(host), { recursive: true, force: true }); rmSync(this.file(name)); return { removed: name, deleted: ['session', 'SynoToken', 'device token', 'App approvals', 'hash pins', 'list cache', 'host registration'] }; }
+    async remove(name) { const host = this.get(name); await this.credentials.delete(this.key(host)); rmSync(this.cacheRoot(host), { recursive: true, force: true }); rmSync(this.file(name)); if (this.defaultName() === name)
+        rmSync(join(this.root, 'default.json'), { force: true }); return { removed: name, deleted: ['session', 'SynoToken', 'device token', 'App approvals', 'hash pins', 'list cache', 'host registration'] }; }
 }

package/dist/ctl/tls.d.ts

@@ -0,0 +1,22 @@
+import https from "node:https";
+import { CtlError } from "./errors.js";
+export interface HostTls {
+    fingerprint?: string;
+    name?: string;
+}
+export declare function normalizeFingerprint(value: string): string;
+export declare function networkError(error: unknown): CtlError;
+export declare function timeoutError(): CtlError;
+/** TLS-only handshake. No HTTP headers, password or session is sent during discovery. */
+export declare function probeCertificate(origin: string, options?: {
+    ca?: string;
+    fingerprint?: string;
+    name?: string;
+    timeoutMs?: number;
+}): Promise<{
+    fingerprint?: string;
+    leafFingerprint?: string;
+    trusted: boolean;
+}>;
+/** Release the socket to HTTPS only after matching the leaf pin on this exact connection. */
+export declare function pinnedAgent(origin: string, trust: HostTls, timeoutMs: number): https.Agent;

package/dist/ctl/tls.js

@@ -0,0 +1,118 @@
+import tls from "node:tls";
+import https from "node:https";
+import { isIP } from "node:net";
+import { CtlError } from "./errors.js";
+export function normalizeFingerprint(value) {
+    const normalized = value.replaceAll(":", "").toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(normalized))
+        throw new CtlError("HOST_FINGERPRINT_INVALID", "A SHA-256 fingerprint must contain 64 hexadecimal digits", "Use the SHA-256 leaf certificate fingerprint", 3);
+    return normalized;
+}
+export function networkError(error) {
+    if (error instanceof CtlError)
+        return error;
+    const code = error?.code;
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return new CtlError("HOST_DNS_FAILED", "NAS hostname could not be resolved", "Check the NAS hostname and DNS", 6);
+    if (code === "ECONNREFUSED")
+        return new CtlError("HOST_CONNECTION_REFUSED", "NAS refused the connection", "Check the DSM port and NAS availability", 6);
+    if (code === "ETIMEDOUT" || code === "ESOCKETTIMEDOUT")
+        return new CtlError("HOST_TIMEOUT", "NAS connection timed out", "Check the NAS connection and firewall", 6);
+    if (code &&
+        /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/.test(code))
+        return new CtlError("HOST_TLS_UNTRUSTED", "NAS TLS certificate is not trusted", "Use synopkgland host login <name>, --ca, or an expected --fingerprint", 6);
+    return new CtlError("CTL_NETWORK", "NAS connection failed", "Check the NAS connection; state-changing requests are not replayed", 6);
+}
+export function timeoutError() {
+    return new CtlError("HOST_TIMEOUT", "NAS connection timed out", "Check the NAS connection and firewall", 6);
+}
+function changed(old, current, name) {
+    return new CtlError("HOST_CERT_CHANGED", `NAS certificate changed: expected SHA-256 ${old}; received ${current}`, `Verify the new certificate, then run: synopkgland host trust ${name ?? "<name>"}`, 6);
+}
+function socketOptions(origin, ca) {
+    const url = new URL(origin), host = url.hostname.replace(/^\[|\]$/g, "");
+    return {
+        host,
+        port: Number(url.port || 443),
+        ...(isIP(host) ? {} : { servername: host }),
+        ...(ca ? { ca } : {}),
+    };
+}
+/** TLS-only handshake. No HTTP headers, password or session is sent during discovery. */
+export function probeCertificate(origin, options = {}) {
+    if (new URL(origin).protocol !== "https:")
+        return Promise.resolve({ trusted: true });
+    return new Promise((resolve, reject) => {
+        const socket = tls.connect({
+            ...socketOptions(origin, options.ca),
+            rejectUnauthorized: false,
+        });
+        const timer = setTimeout(() => socket.destroy(timeoutError()), options.timeoutMs ?? 30000);
+        socket.once("error", (e) => reject(networkError(e)));
+        socket.once("close", () => clearTimeout(timer));
+        socket.once("secureConnect", () => {
+            try {
+                const raw = socket.getPeerCertificate().fingerprint256;
+                if (!raw)
+                    throw new CtlError("HOST_TLS_UNTRUSTED", "NAS did not provide a leaf certificate", "Check the NAS HTTPS endpoint", 6);
+                const fingerprint = normalizeFingerprint(raw);
+                if (options.fingerprint &&
+                    normalizeFingerprint(options.fingerprint) !== fingerprint)
+                    throw changed(normalizeFingerprint(options.fingerprint), fingerprint, options.name);
+                // A caller-provided CA is an explicit trust policy, never a TOFU fallback.
+                if (options.ca && !socket.authorized)
+                    throw new CtlError("HOST_TLS_UNTRUSTED", "NAS certificate was not verified by the supplied CA", "Check the CA file and NAS hostname", 6);
+                resolve({
+                    trusted: socket.authorized,
+                    leafFingerprint: fingerprint,
+                    fingerprint: options.fingerprint || !socket.authorized ? fingerprint : undefined,
+                });
+            }
+            catch (e) {
+                reject(e);
+            }
+            finally {
+                socket.destroy();
+            }
+        });
+    });
+}
+/** Release the socket to HTTPS only after matching the leaf pin on this exact connection. */
+export function pinnedAgent(origin, trust, timeoutMs) {
+    const agent = new https.Agent({ keepAlive: false });
+    agent.createConnection = (_options, callback) => {
+        let done = false;
+        const socket = tls.connect({
+            ...socketOptions(origin),
+            rejectUnauthorized: false,
+        });
+        const timer = setTimeout(() => socket.destroy(timeoutError()), timeoutMs);
+        const finish = (error) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (error) {
+                socket.destroy();
+                callback?.(error, null);
+            }
+            else
+                callback?.(null, socket);
+        };
+        socket.once("error", (e) => finish(networkError(e)));
+        socket.once("secureConnect", () => {
+            try {
+                const current = normalizeFingerprint(socket.getPeerCertificate().fingerprint256 ?? "");
+                const old = normalizeFingerprint(trust.fingerprint);
+                if (old !== current)
+                    throw changed(old, current, trust.name);
+                finish();
+            }
+            catch (e) {
+                finish(e);
+            }
+        });
+        return undefined;
+    };
+    return agent;
+}