@synopackageland/cli 0.32.1 → 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/dist/skill.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const SKILL_CATALOG = [
     { id: "orchestrator", file: "SKILL.md", when: "Read first" },
+    { id: "host-install", file: "reference/host-install.md", when: "Shared NAS login, store/local SPK installation and removal" },
     { id: "ctl", file: "reference/ctl.md", when: "Operate registered NAS Apps or design AI commands" },
     {
         id: "create",

package/dist/spk/inspect.d.ts

@@ -3,6 +3,7 @@ import { type SpkFinding } from "./validate-spk.js";
 export interface SpkReport extends SpkInspection {
     /** Built by synopkgland, so its build contract (`findings`) was checked too. */
     synopkgland: boolean;
+    info?: Record<string, string>;
     /** The DSM 7 package format rules, checked on every SPK. */
     dsm: {
         ok: boolean;

package/dist/spk/inspect.js

@@ -19,7 +19,7 @@ export async function inspectAnySpk(spkPath) {
     const dsm = { ok: validation.ok, errors: validation.errors, warnings: validation.warnings };
     const facts = await readFacts(spkPath);
     if (BUILD_MARKERS.some((name) => facts.top.has(name)) || facts.payload.some((entry) => entry.path === CONTAINER_MARKER)) {
-        return { ...(await inspectSpk(spkPath)), synopkgland: true, dsm };
+        return { ...(await inspectSpk(spkPath)), synopkgland: true, info: validation.info, dsm };
     }
     return {
         ...(validation.package ? { package: validation.package } : {}),
@@ -30,6 +30,7 @@ export async function inspectAnySpk(spkPath) {
         findings: [],
         capabilities: [],
         synopkgland: false,
+        info: validation.info,
         dsm,
     };
 }

package/dist/spk/validate-spk.d.ts

@@ -3,6 +3,7 @@ export type { SpkFinding } from "./findings.js";
 export interface SpkValidation {
     /** No errors; warnings do not fail validation. */
     ok: boolean;
+    info?: Record<string, string>;
     package?: string;
     version?: string;
     arch?: string;

package/dist/spk/validate-spk.js

@@ -34,6 +34,7 @@ export async function validateSpk(spkPath) {
     const errors = findings.list.filter((finding) => finding.severity === "error");
     return {
         ok: errors.length === 0,
+        info,
         ...(info.package ? { package: info.package } : {}),
         ...(info.version ? { version: info.version } : {}),
         ...(info.arch ? { arch: info.arch } : {}),

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.32.1",
+  "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，禁止發明新的身分平台。
@@ -48,6 +50,8 @@ Buttons follow DSM's policy ([reference/ui-vue.md](reference/ui-vue.md#buttons),
 
 Read [reference/ui-json.md](reference/ui-json.md) when generating or editing JSON UI; discover the installed catalog, validate the spec, then render and fix layout issues.
 
+Read [reference/host-install.md](reference/host-install.md) before NAS authentication, store/local-SPK installation or package removal. All DSM commands share the registered host session.
+
 ## UI copywriting
 
 For UI/locale strings we author in the SDK, UI package, templates and our own

package/skills/reference/ctl.md

@@ -1,16 +1,18 @@
 # 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 ctl host list --json` checks registered machines and sessions.
-2. Register with `ctl host add nas --url https://nas.example:5001 --username alice`, or renew with `ctl host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
+1. `synopkgland host list --json` checks registered machines and sessions.
+2. Register with `host add nas --url https://nas.example:5001 --username alice`, or renew with `host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
 3. Run `synopkgland ctl list --host nas --json` for all registered Apps, commands, schemas, effects, permissions and executable examples. If description access needs approval, ask the user to approve the whole candidate batch; do not self-approve. An explicit `--approve-installed` records permission to send the DSM session to the displayed inventory's fixed description endpoints. Use `--app <package>` to narrow the batch. No description endpoint is anonymous.
 4. Use the discovered alias, CLI path and typed flags with an explicit `--host nas`; inspect `--help` and `--dry-run` before execution. For example, `synopkgland ctl notes list --status pending --host nas --dry-run`. Use the real command/schema from discovery, not this illustrative name.
 5. Reads need no write confirmation. For authorized write/destructive commands, add `--yes`; without it the CLI returns a plan and confirmation error. A --yes flag does not replace the user's authorization or the App's backend checks.
 
-There is no shared current context: with multiple hosts, always specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
+With multiple hosts, select a default with `synopkgland host default <name>` or specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
 
-Use `ctl host show nas` to inspect approvals/pins, `ctl host revoke nas PackageID` to remove an App approval, `ctl host logout nas` to retain registration, and `ctl host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
+Use `host show nas` to inspect approvals/pins, `host revoke nas PackageID` to remove an App approval, `host logout nas` to retain registration, and `host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.
 

package/skills/reference/deploy.md

@@ -1,3 +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

@@ -0,0 +1,66 @@
+# Shared NAS login and package installation
+
+Register once with `synopkgland host add nas --url https://nas.example:5001 --username alice`.
+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.
+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
+`host revoke nas <package-id>` manage the registration, login and App approvals.
+`host default nas` selects a default; with one host it is selected automatically.
+Every DSM command accepts `--host nas`, including ctl, deploy, status, logs,
+install and uninstall. ctl still requires explicit App description approval.
+
+For authorized package changes:
+
+```sh
+synopkgland install SynoReclaim --host nas --dry-run --json
+synopkgland install SynoReclaim --host nas --yes --json
+synopkgland install SynoReclaim@0.1.1-1591 --host nas --yes
+synopkgland install ./MyApp.spk --host nas --param NAME=value --yes
+synopkgland status SynoReclaim --host nas --json
+synopkgland uninstall SynoReclaim --host nas --yes --json
+```
+
+Store installs default to `https://packages.synopkgland.com`; `--source <HTTPS URL>`
+selects another source. The source is queried for the NAS platform and DSM build.
+The CLI plans dependencies from the same feed, reports missing Synology packages,
+checks every feed size/MD5/SHA-256 pin and inspects SPKs before uploading.
+`<package-id>@version` selects an exact available release; downgrades are refused.
+`--dry-run` reads NAS/source metadata and prints the plan without uploading or changing DSM.
+Local SPKs pass the same inspect, architecture and DSM checks before installation.
+The inspection reports signature presence; it does not cryptographically authenticate a publisher.
+Install wizard values use repeated `--param NAME=value`; values are private and
+not printed in plans. DSM package hooks validate their meaning. Install/removal
+require administrator rights. Uninstall hooks can remove package data; review the App's policy.
+A failed multi-package install may leave earlier dependencies installed; inspect status before retrying.
+
+For automation, provide `DSM_USERNAME` and `DSM_PASSWORD` in the process environment
+(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. 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.
+
+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.