@synopackageland/cli 0.33.0 → 0.33.1

package/dist/nas/tls.js

@@ -0,0 +1,129 @@
+import tls from "node:tls";
+import https from "node:https";
+import { isIP } from "node:net";
+import { CtlError } from "../ctl/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 &&
+        (code === "DSM_TLS_UNTRUSTED" || /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/.test(code)))
+        return new CtlError("HOST_TLS_UNTRUSTED", "NAS TLS certificate is not trusted", "Check the CA file, NAS hostname and certificate validity, or omit strict TLS", 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);
+                checkCertificate(socket, { ...options, expectedFingerprint: options.expectedFingerprint });
+                resolve({
+                    trusted: socket.authorized,
+                    leafFingerprint: fingerprint,
+                    fingerprint: fingerprint,
+                });
+            }
+            catch (e) {
+                reject(e);
+            }
+            finally {
+                socket.destroy();
+            }
+        });
+    });
+}
+/** Inspect the certificate and apply NAS policy before releasing this exact socket to HTTP. */
+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, trust.ca),
+            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 {
+                checkCertificate(socket, trust);
+                finish();
+            }
+            catch (e) {
+                finish(e);
+            }
+        });
+        return undefined;
+    };
+    return agent;
+}
+/** Runs before HTTP can write headers or a password on this very socket. */
+function checkCertificate(socket, trust) {
+    const current = normalizeFingerprint(socket.getPeerCertificate().fingerprint256 ?? '');
+    const recorded = trust.readFingerprint?.() ?? trust.fingerprint;
+    const old = recorded && normalizeFingerprint(recorded);
+    const expected = trust.expectedFingerprint && normalizeFingerprint(trust.expectedFingerprint);
+    if (expected && expected !== current)
+        throw changed(expected, current, trust.name);
+    if (old && old !== current && (trust.strictTls || trust.ca))
+        throw changed(old, current, trust.name);
+    if ((trust.strictTls || trust.ca) && !socket.authorized)
+        throw new CtlError('HOST_TLS_UNTRUSTED', 'NAS certificate failed CA, hostname or validity verification', 'Check the CA file, NAS hostname and certificate validity', 6);
+    if (old && old !== current)
+        (trust.warn ?? console.error)(`NAS certificate changed: ${old.slice(0, 16)} -> ${current.slice(0, 16)}, now trusting the new one`);
+    if (old !== current) {
+        trust.record?.(current);
+        trust.fingerprint = current;
+    }
+}

package/dist/nas/transfers.d.ts

@@ -0,0 +1,16 @@
+import { type HostTls } from './tls.js';
+import { type DsmSession } from './transport.js';
+export declare function localFile(file: unknown): {
+    file: string;
+    size: number;
+};
+export declare function transferRequest(session: DsmSession, path: string, method: string, params: Record<string, unknown>, options?: {
+    file?: {
+        path: string;
+        parent: string;
+        name: string;
+    };
+    ca?: string;
+    timeoutMs?: number;
+    trust?: HostTls;
+}): Promise<any>;

package/dist/nas/transfers.js

@@ -0,0 +1,76 @@
+import { networkError, timeoutError } from './tls.js';
+import { createReadStream, statSync } from 'node:fs';
+import { CtlError } from '../ctl/errors.js';
+import { nasHttpRequest, CTL_TIMEOUT_MS } from './transport.js';
+export function localFile(file) { if (typeof file !== 'string' || !file)
+    throw new CtlError('CTL_INPUT_FILE', 'A local filename is required.', 'Use --file <path>.'); try {
+    const stat = statSync(file);
+    if (!stat.isFile() || stat.size > 16 * 1024 ** 3)
+        throw Error();
+    return { file, size: stat.size };
+}
+catch {
+    throw new CtlError('CTL_INPUT_FILE', 'Upload must be a readable regular file of at most 16 GiB.', 'Check --file <path>.');
+} }
+export async function transferRequest(session, path, method, params, options = {}) {
+    if (!/^\/webman\/3rdparty\/[A-Za-z][A-Za-z0-9_.+-]*\/cgi\/api\.cgi$/.test(path) || !/^([a-z][a-z0-9_]*\.)+[a-z][a-z0-9_]*$/.test(method))
+        throw new CtlError('CTL_PATH_INVALID', 'Invalid transfer binding.', 'Refresh the API description.', 4);
+    if (options.timeoutMs !== undefined && options.timeoutMs <= 0)
+        throw new CtlError('CTL_NETWORK', 'Transfer budget exhausted before dispatch.', 'Check App state before retrying writes.', 6);
+    const url = new URL(path, session.origin);
+    const file = options.file ? localFile(options.file.path) : undefined;
+    if (options.file) {
+        url.search = new URLSearchParams({ method, parent: options.file.parent, name: options.file.name }).toString();
+    }
+    const raw = file ? undefined : Buffer.from(JSON.stringify({ method, params }));
+    return new Promise((resolve, reject) => {
+        const headers = { 'content-type': file ? 'application/octet-stream' : 'application/json', cookie: session.cookie, 'X-SYNO-TOKEN': session.token, origin: session.origin, 'content-length': String(file?.size ?? raw.length) };
+        const req = nasHttpRequest(url, { method: 'POST', headers }, options.timeoutMs ?? CTL_TIMEOUT_MS, { ...options.trust, ca: options.ca ?? options.trust?.ca }, res => {
+            const expected = file ? 'application/json' : 'application/x-ndjson';
+            if (res.statusCode !== 200 || !res.headers['content-type']?.includes(expected)) {
+                res.resume();
+                reject(new CtlError('CTL_TRANSFER_FAILED', 'Unexpected transfer response; redirects are refused.', 'Check App transfer support.', 5));
+                return;
+            }
+            const chunks = [];
+            let total = 0;
+            res.on('data', (chunk) => { total += chunk.length; if (total > (file ? 1048576 : 8 * 1048576)) {
+                req.destroy();
+                reject(new CtlError('CTL_FLOW_LIMIT', 'Transfer result exceeds collection limit.', 'Narrow the query.', 5));
+            }
+            else
+                chunks.push(chunk); });
+            res.on('error', () => reject(new CtlError('CTL_NETWORK', 'Transfer response interrupted.', 'Check state before retrying writes.', 6)));
+            res.on('end', () => { try {
+                const text = Buffer.concat(chunks).toString('utf8');
+                if (file) {
+                    const body = JSON.parse(text);
+                    if (body.success !== true)
+                        throw Error();
+                    resolve(body.data);
+                }
+                else {
+                    const lines = text.split('\n').filter(l => l.trim());
+                    if (lines.length > 10000)
+                        throw Error();
+                    resolve({ items: lines.map(line => JSON.parse(line)) });
+                }
+            }
+            catch {
+                reject(new CtlError('CTL_TRANSFER_FAILED', 'Invalid or failed transfer response.', 'Inspect the App result; do not retry writes blindly.', 5));
+            } });
+        });
+        const wallTimer = setTimeout(() => req.destroy(timeoutError()), options.timeoutMs ?? CTL_TIMEOUT_MS);
+        req.once('close', () => clearTimeout(wallTimer));
+        req.on('timeout', () => req.destroy(timeoutError()));
+        req.on('error', e => reject(networkError(e)));
+        if (file) {
+            const source = createReadStream(file.file);
+            source.on('error', () => req.destroy());
+            req.on('close', () => source.destroy());
+            source.pipe(req);
+        }
+        else
+            req.end(raw);
+    });
+}

package/dist/nas/transport.d.ts

@@ -0,0 +1,17 @@
+import { type HostTls } from './tls.js';
+import http from 'node:http';
+export declare const CTL_TIMEOUT_MS = 62000;
+export declare const APP_COOKIE: unique symbol;
+export interface DsmSession {
+    origin: string;
+    username: string;
+    cookie: string;
+    token: string;
+    deviceId?: string;
+}
+export type JsonRequest = (path: string, body: URLSearchParams | Record<string, unknown>, session?: DsmSession) => Promise<any>;
+export declare function canonicalOrigin(input: string, tunnel?: boolean): string;
+export declare function createRequest(origin: string, timeoutMs?: number | (() => number), ca?: string, trust?: HostTls): JsonRequest;
+export declare function sessionFetch(url: string, init: RequestInit, session: DsmSession | undefined, ca?: string, trust?: HostTls): Promise<Response>;
+/** The only Node HTTP dispatch for NAS endpoints, including streaming transfers. */
+export declare function nasHttpRequest(url: URL, options: http.RequestOptions, timeoutMs: number, trust: HostTls | undefined, listener: (res: http.IncomingMessage) => void): http.ClientRequest;

package/dist/nas/transport.js

@@ -0,0 +1,143 @@
+import { pinnedAgent, networkError, timeoutError } from './tls.js';
+import { strictJson } from '../ctl/json.js';
+import http from 'node:http';
+import https from 'node:https';
+import { assertSessionActive } from './session.js';
+import { nasOptions } from './options.js';
+import { readFileSync } from 'node:fs';
+import { CtlError } from '../ctl/errors.js';
+export const CTL_TIMEOUT_MS = 62000;
+export const APP_COOKIE = Symbol("ctlAppCookie");
+export function canonicalOrigin(input, tunnel = false) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new CtlError('CTL_URL_INVALID', 'A NAS origin URL is required.', 'run: synopkgland host add <name> --url https://<nas>:5001');
+    }
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || !(url.protocol === 'https:' || (tunnel && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))))
+        throw new CtlError('CTL_URL_INVALID', 'Use HTTPS, or explicit --ssh-tunnel for a loopback HTTP tunnel.', 'run: synopkgland host add <name> --url https://<nas>:5001');
+    return url.origin;
+}
+export function createRequest(origin, timeoutMs = CTL_TIMEOUT_MS, ca, trust) {
+    return async (path, body, session) => {
+        if (!path.startsWith('/') || path.startsWith('//') || path.includes('?') || path.includes('#') || path.includes('\\') || path.includes('%') || path.split('/').some(p => p === '.' || p === '..'))
+            throw new CtlError('CTL_PATH_INVALID', 'Unsafe request path.', 'run: synopkgland ctl list --refresh');
+        const remaining = typeof timeoutMs === 'function' ? timeoutMs() : timeoutMs;
+        if (remaining <= 0)
+            throw new CtlError('CTL_NETWORK', 'Request budget exhausted before dispatch.', 'Check App state before retrying writes.', 6);
+        const url = new URL(path, origin);
+        if (url.origin !== origin || (session && session.origin !== origin))
+            throw new CtlError('CTL_ORIGIN_MISMATCH', 'Credentials cannot cross NAS origins.', 'run: synopkgland host list', 4);
+        const form = body instanceof URLSearchParams;
+        const payload = Buffer.from(form ? body.toString() : JSON.stringify(body));
+        if (payload.length > 1048576)
+            throw new CtlError('CTL_INPUT_TOO_LARGE', 'Request exceeds 1 MiB.', 'Reduce the input.');
+        return new Promise((resolve, reject) => {
+            const headers = { 'content-type': form ? 'application/x-www-form-urlencoded' : 'application/json', accept: 'application/json', 'content-length': String(payload.length), origin };
+            if (session) {
+                headers.cookie = session.cookie;
+                headers['X-SYNO-TOKEN'] = session.token;
+            }
+            const req = nasHttpRequest(url, { method: 'POST', headers }, remaining, trustWithCa(trust, ca), res => {
+                if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                    res.resume();
+                    reject(new CtlError('CTL_HTTP_ERROR', `HTTP ${res.statusCode}; redirects are never followed.`, 'Check the NAS URL and connection.', 6));
+                    return;
+                }
+                if (!res.headers['content-type']?.includes('application/json')) {
+                    res.resume();
+                    reject(new CtlError('CTL_RESPONSE_INVALID', 'NAS returned non-JSON data.', 'Check the endpoint and installed package.', 5));
+                    return;
+                }
+                const chunks = [];
+                let length = 0;
+                res.on('data', (c) => { length += c.length; if (length > 1048576) {
+                    res.destroy();
+                    reject(new CtlError('CTL_RESPONSE_TOO_LARGE', 'Response exceeds 1 MiB.', 'Use a smaller operation.', 5));
+                }
+                else
+                    chunks.push(c); });
+                res.on('error', () => reject(new CtlError('CTL_NETWORK', 'Response interrupted.', 'Check the NAS connection; state-changing requests are not replayed.', 6)));
+                res.on('end', () => {
+                    try {
+                        const body = strictJson(Buffer.concat(chunks));
+                        if (session && path === '/webapi/entry.cgi')
+                            assertSessionActive(body, trust?.name);
+                        if (!form && body?.success === true && body.data && path.startsWith('/webman/3rdparty/') && url.protocol === 'https:') {
+                            const cookies = (res.headers['set-cookie'] ?? []).filter(line => /;\s*Secure(?:;|$)/i.test(line) && /;\s*HttpOnly(?:;|$)/i.test(line) && !/;\s*Domain=/i.test(line));
+                            const own = path.slice(0, path.lastIndexOf('/cgi/')) + '/';
+                            const valid = cookies.filter(line => { const match = /;\s*Path=([^;]+)/i.exec(line); return match?.[1] === own; }).map(line => line.split(';')[0]).filter(pair => !pair.startsWith('id='));
+                            if (valid.length)
+                                Object.defineProperty(body, APP_COOKIE, { value: valid.join('; '), enumerable: false });
+                        }
+                        resolve(body);
+                    }
+                    catch (error) {
+                        if (error instanceof CtlError) {
+                            reject(error);
+                            return;
+                        }
+                        reject(new CtlError('CTL_RESPONSE_INVALID', 'Invalid JSON response.', 'Check the installed package.', 5));
+                    }
+                });
+            });
+            const wallTimer = setTimeout(() => req.destroy(timeoutError()), remaining);
+            req.once('close', () => clearTimeout(wallTimer));
+            req.on('timeout', () => req.destroy(timeoutError()));
+            req.on('error', error => reject(networkError(error)));
+            req.end(payload);
+        });
+    };
+}
+export async function sessionFetch(url, init, session, ca, trust) {
+    if (session && new URL(url).origin !== session.origin)
+        throw new CtlError('CTL_ORIGIN_MISMATCH', 'Credentials cannot cross NAS origins', 'Check the registered NAS origin', 4);
+    const headers = new Headers(init.headers);
+    if (session) {
+        headers.set('cookie', session.cookie);
+        headers.set('X-SYNO-TOKEN', session.token);
+    }
+    const request = new Request(url, { ...init, headers }), bytes = init.body ? Buffer.from(await request.arrayBuffer()) : undefined;
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const req = nasHttpRequest(target, { method: request.method, headers: Object.fromEntries(request.headers) }, 62000, trustWithCa(trust, ca), res => {
+            const chunks = [];
+            let length = 0;
+            res.on('data', c => { length += c.length; if (length > 16 * 1024 * 1024)
+                res.destroy(new CtlError('CTL_RESPONSE_TOO_LARGE', 'DSM response exceeds 16 MiB', 'Use a narrower operation', 5));
+            else
+                chunks.push(c); });
+            res.on('error', () => reject(new CtlError('DSM_NETWORK', 'DSM response interrupted', 'Check the NAS connection', 6)));
+            res.on('end', () => { const headers = new Headers(); for (const [k, v] of Object.entries(res.headers))
+                for (const x of Array.isArray(v) ? v : [v])
+                    if (x !== undefined)
+                        headers.append(k, x); resolve(new Response([204, 205, 304].includes(res.statusCode ?? 0) || request.method === 'HEAD' ? null : Buffer.concat(chunks), { status: res.statusCode, headers })); });
+        });
+        const abort = () => req.destroy(request.signal.reason instanceof Error ? request.signal.reason : new Error('Request aborted'));
+        if (request.signal.aborted)
+            abort();
+        else
+            request.signal.addEventListener('abort', abort, { once: true });
+        req.once('close', () => request.signal.removeEventListener('abort', abort));
+        const timer = setTimeout(() => req.destroy(timeoutError()), 62000);
+        req.once('close', () => clearTimeout(timer));
+        req.on('timeout', () => req.destroy(timeoutError()));
+        req.on('error', e => reject(networkError(e)));
+        req.end(bytes);
+    });
+}
+/** The only Node HTTP dispatch for NAS endpoints, including streaming transfers. */
+export function nasHttpRequest(url, options, timeoutMs, trust = {}, listener) {
+    const override = nasOptions();
+    const policy = { ...trust, get fingerprint() { return trust.fingerprint; }, set fingerprint(value) { trust.fingerprint = value; }, strictTls: trust.strictTls || override.strictTls, ca: override.ca ? readFileSync(override.ca, 'utf8') : trust.ca, warn: trust.warn ?? override.warn };
+    const agent = url.protocol === 'https:' ? pinnedAgent(url.origin, policy, timeoutMs) : undefined;
+    // Share observations with this request factory, so parallel requests warn once.
+    policy.record = (fingerprint) => { trust.record?.(fingerprint); trust.fingerprint = fingerprint; };
+    const req = (url.protocol === 'https:' ? https : http).request(url, { ...options, timeout: timeoutMs, ...(agent ? { agent } : {}) }, listener);
+    req.once('close', () => agent?.destroy());
+    return req;
+}
+function trustWithCa(trust, ca) { const policy = trust ?? {}; if (ca)
+    policy.ca = ca; return policy; }

package/dist/package-source.d.ts

@@ -0,0 +1,2 @@
+/** Public package feeds and SPK downloads use normal public HTTPS verification. */
+export declare function fetchPackageSource(url: string): Promise<Response>;

package/dist/package-source.js

@@ -0,0 +1,4 @@
+/** Public package feeds and SPK downloads use normal public HTTPS verification. */
+export function fetchPackageSource(url) {
+    return fetch(url, { redirect: 'error', signal: AbortSignal.timeout(62000) });
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
-    "synopkgland": "./dist/bin.js"
+    "synopkgland": "dist/bin.js"
   },
   "engines": {
     "node": ">=22.12"

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-CLI 0.32.1 installs templates through `~0.31.0`. A templates patch needs only a
+CLI 0.33.1 installs templates through `~0.31.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -16,6 +16,8 @@ The CLI verifies bytes before packaging and never fetches a manifest at NAS runt
 Unsupported formats require a CLI update; invalid manifests fail closed. Existing
 SDK 0.26.0/0.27.0 use the frozen legacy inventory.
 
+All CLI NAS requests share one connection path. NAS certificates are accepted by default, including self-signed, wrong-name and expired certificates. A changed certificate warns once, updates its displayed SHA-256 and continues. `host add --strict-tls` stores strict verification; `--strict-tls` or `--ca <file>` on a command opts in for that command. Read [reference/host-install.md](reference/host-install.md) for host trust and error codes.
+
 Before releasing an executor App, read [reference/approval-upgrades.md](reference/approval-upgrades.md). Run build/inspect with the previous released SPK as `--baseline` and include the approval difference in release notes. Without a comparable baseline, retention is unknown.
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。

package/skills/reference/ctl.md

@@ -1,5 +1,7 @@
 # Control registered NAS Apps with ctl
 
+NAS HTTPS accepts any certificate by default. A changed leaf warns and updates the recorded SHA-256. Use `--strict-tls` or `--ca <file>` to opt into CA, hostname, expiry and change checks; host add stores that policy. See [host login](host-install.md).
+
 Use this for operating installed Apps, rather than building/deploying projects.
 
 1. `synopkgland host list --json` checks registered machines and sessions.

package/skills/reference/deploy.md

@@ -1,5 +1,7 @@
 Before deployment, register a NAS with `synopkgland host add nas --url https://nas.example:5001`, then renew it with `synopkgland host login nas`. See [host-install.md](host-install.md) for shared sessions, automation, install and uninstall.
 
+NAS HTTPS accepts any certificate by default. A changed leaf warns and updates the recorded SHA-256. Use `--strict-tls` or `--ca <file>` to opt into CA, hostname, expiry and change checks; host add stores that policy. See [host login](host-install.md).
+
 # Build and deploy
 
 1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 or armv7 for those targets; armv7 must be listed in `arches`; its jobs, daemon and executor are built but not NAS-verified). deploy detects the NAS arch, except on Marvell CPUs, where it asks for `--arch`.

package/skills/reference/host-install.md

@@ -4,7 +4,7 @@ Register once with `synopkgland host add nas --url https://nas.example:5001 --us
 The CLI prompts for the password and OTP when DSM requires it. Session cookies,
 SynoToken and remembered-device tokens stay in the OS credential store; host
 metadata and App approvals stay under `~/.synopkgland/ctl`. Passwords are not saved.
-Use `--ca <PEM>` when adding a host with a private CA. Certificate verification stays on.
+NAS HTTPS accepts every certificate by default, including self-signed, untrusted CA, wrong-name and expired certificates. Use `--strict-tls` or `--ca <PEM>` to opt into verification.
 
 Use `synopkgland host login nas` to renew an expired session. `host list`,
 `host show nas`, `host logout nas`, `host remove nas --yes` and
@@ -41,15 +41,26 @@ For automation, provide `DSM_USERNAME` and `DSM_PASSWORD` in the process environ
 (and `DSM_OTP` if required), with a registered `--host` using that same account.
 These values create an in-memory session and are never written to disk. Without a
 registration, install/deploy/status/logs also accept `DSM_URL` with both credentials.
-Use an HTTPS URL and a trusted certificate. Supply secrets through your CI secret
+Use an HTTPS URL. Supply secrets through your CI secret
 store, never literal command arguments, committed files or command output.
 `host add/login --password-stdin` supports a password from standard input.
 
-Default NAS HTTPS certificates work through trust on first use: before sending a
-password, the CLI pins an untrusted leaf certificate's SHA-256 and prints
-`Trusting the NAS certificate <short fingerprint> (self-signed)`. Subsequent
-requests check the exact leaf. `HOST_CERT_CHANGED` shows old/new fingerprints;
-verify them with the user, then use `synopkgland host trust <name>` only after
-confirmation. Never disable TLS checks. `host add --fingerprint <sha256>` pins an
-expected leaf; `--ca <PEM>` uses a CA instead. Network errors distinguish
-HOST_TLS_UNTRUSTED, HOST_DNS_FAILED, HOST_CONNECTION_REFUSED and HOST_TIMEOUT.
+Every NAS request uses one shared connection module for host lookup, login,
+OS session storage, expiry handling, TLS and HTTP, including ctl transfers,
+install, uninstall, deploy, dev, status, logs and e2e login helpers. Passwords
+are sent only after inspecting the certificate on that exact TLS connection.
+The leaf SHA-256 is recorded for display. An unverified first connection says
+`Trusting the NAS certificate <short fingerprint> (not verified by a trusted CA)`.
+A changed certificate prints one stderr line, updates the recorded fingerprint
+and continues: `NAS certificate changed: <old short> -> <new short>, now trusting the new one`.
+
+`host add --strict-tls` stores strict mode in the host profile. `--strict-tls`
+on another command applies to that invocation only. Strict mode checks the CA,
+hostname, expiry and recorded fingerprint: untrusted certificates fail with
+`HOST_TLS_UNTRUSTED`; changed certificates fail with `HOST_CERT_CHANGED`.
+`--ca <PEM>` also opts into real CA and hostname verification and is stored on
+host add, or applies to one command. `host trust <name>` still replaces a recorded
+fingerprint after confirmation. `host add --fingerprint <sha256>` checks an
+explicit expected leaf during registration; it does not turn on strict mode.
+No global TLS override is used. Public package feeds and downloads keep normal
+HTTPS verification. Network errors distinguish DNS, refusal and timeout.