@synopackageland/cli 0.32.0 → 0.33.0

package/dist/host/dsm-client.js

@@ -1,11 +1,11 @@
-import { spawnSync } from "node:child_process";
-import { listShareNamesWithSynoagentcli, lookupSharePathWithSynoagentcli, } from "./share-lookup.js";
-import { createSynoagentcliApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
+import { CtlError } from '../ctl/errors.js';
+import { listShareNames, lookupSharePath, } from "./share-lookup.js";
+import { createDsmApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
 import { fetchPortInfo } from "./port-info-lookup.js";
-import { dsmFetch } from "./dsm-http.js";
+import { dsmFetch, registerDsmSession } from "./dsm-http.js";
 import { versionUnsupported } from "../runtime/dsm-version.js";
 import { fetchDsmPortProfileInventory } from "./dsm-port-profile.js";
-import { installPackageFromLocalSpk, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
+import { installPackageFromLocalSpk, fetchInstalledPackageState, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
 export function createNasHost(options = {}) {
     const credentials = options.credentials ?? resolveHostCredentials(options.host);
@@ -14,18 +14,6 @@ export function createNasHost(options = {}) {
     }
     return createDsmNasHost(credentials, options.host);
 }
-function synoagentcli(args, profileName) {
-    const fullArgs = [...args];
-    if (profileName) {
-        fullArgs.push("--host", profileName);
-    }
-    const result = spawnSync("synoagentcli", fullArgs, { encoding: "utf8" });
-    return {
-        status: result.status,
-        stdout: result.stdout ?? "",
-        stderr: result.stderr ?? "",
-    };
-}
 /**
  * DSM's User Home read reports the selected volume, not the final share path.
  * Keep the projection strict: an unexpected response must not become a host
@@ -68,6 +56,11 @@ function createDsmNasHost(credentials, profileName) {
     const dsmOrigin = credentials.dsmOrigin.replace(/\/$/, "");
     let cookieHeader = credentials.cookieHeader;
     const ensureLogin = async () => {
+        if (credentials.loadSession && !cookieHeader) {
+            const session = await credentials.loadSession();
+            cookieHeader = session.cookie;
+            registerDsmSession(session, credentials.hostName ?? profileName ?? 'env', credentials.ca, credentials.fingerprint);
+        }
         if (cookieHeader) {
             return;
         }
@@ -76,7 +69,7 @@ function createDsmNasHost(credentials, profileName) {
             version: "3",
             method: "login",
             account: credentials.username,
-            passwd: credentials.password,
+            passwd: credentials.password ?? "",
             session: "FileStation",
             format: "cookie",
         });
@@ -129,10 +122,21 @@ function createDsmNasHost(credentials, profileName) {
             await appCall("identity.logout", appCookie).catch(() => undefined);
         }
     };
+    const call = async (api, method, version, params = {}) => {
+        await ensureLogin();
+        const response = await dsmFetch(`${dsmOrigin}/webapi/entry.cgi`, { method: 'POST', headers: { cookie: cookieHeader ?? '', 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ api, method, version: String(version), ...params }) });
+        const body = await response.json();
+        if (body?.success !== true)
+            throw Object.assign(new Error(`DSM ${api}/${method} failed (${Number(body?.error?.code) || 'invalid response'})`), { code: body?.error?.code });
+        return body;
+    };
     return {
         dsmOrigin,
         async installFromLocalSpk(input) {
             await ensureLogin();
+            const members = await call('SYNO.Core.Group.Member', 'list', 1, { group: 'administrators', offset: '0', limit: '-1' });
+            if (!Array.isArray(members.data?.users) || !members.data.users.some((u) => u.name === credentials.username))
+                throw new CtlError('NAS_ADMIN_REQUIRED', 'Package installation requires a DSM administrator account', 'Log in with a DSM administrator account', 4);
             await installPackageFromLocalSpk({
                 dsmOrigin,
                 cookieHeader: cookieHeader ?? "",
@@ -154,7 +158,9 @@ function createDsmNasHost(credentials, profileName) {
                     return { ready: false, executor_digest: "", policy_digest: "", error: read.error };
                 return explain(read.data);
             }
-            catch {
+            catch (error) {
+                if (error instanceof CtlError)
+                    throw error;
                 return undefined;
             }
         },
@@ -163,7 +169,9 @@ function createDsmNasHost(credentials, profileName) {
                 const read = await readApp(packageIdentity, "portal.status");
                 return read && "data" in read ? read.data : undefined;
             }
-            catch {
+            catch (error) {
+                if (error instanceof CtlError)
+                    throw error;
                 return undefined;
             }
         },
@@ -218,110 +226,57 @@ function createDsmNasHost(credentials, profileName) {
             const response = await dsmFetch(`${dsmOrigin}/webapi/entry.cgi?api=SYNO.Core.System&version=1&method=info`, { headers: { cookie: cookieHeader ?? "" } });
             const body = (await response.json());
             if (body.success !== true) {
+                if (Number(body.error?.code) === 105)
+                    throw new CtlError('NAS_ADMIN_REQUIRED', 'NAS deployment requires a DSM administrator account', 'Log in with a DSM administrator account', 4);
                 return undefined;
             }
             return archFamilyForCpuVendor(body.data?.cpu_vendor);
         },
         async resolveSharePath(logicalName) {
-            return lookupSharePathWithSynoagentcli(logicalName, profileName);
+            return lookupSharePath(logicalName, call);
         },
         async listShareNames() {
-            return listShareNamesWithSynoagentcli(profileName);
+            return listShareNames(call);
         },
         async listSharePermissions(logicalName) {
-            return fetchSharePermissions(logicalName, createSynoagentcliApiCall(profileName));
+            return fetchSharePermissions(logicalName, createDsmApiCall(call));
         },
         async listUserGroups(userName) {
-            return fetchUserGroups(userName, createSynoagentcliApiCall(profileName));
+            return fetchUserGroups(userName, createDsmApiCall(call));
         },
         async listPortInfo() {
             try {
                 await ensureLogin();
                 return fetchPortInfo(dsmOrigin, cookieHeader ?? "");
             }
-            catch {
+            catch (error) {
+                if (error instanceof CtlError)
+                    throw error;
                 return undefined;
             }
         },
         async resolveHomesPath() {
-            try {
-                const result = synoagentcli([
-                    "dsm",
-                    "control-panel",
-                    "user-group",
-                    "advanced",
-                    "get",
-                    "--section",
-                    "home",
-                ], profileName);
-                return homesPathFromDsmUserHomeRead(result);
-            }
-            catch {
-                return undefined;
-            }
+            const body = await call('SYNO.Core.User.Home', 'get', 1);
+            return homesPathFromDsmUserHomeRead({ status: 0, stdout: JSON.stringify(body) });
         },
         async getInstalledPackageState(packageIdentity) {
             await ensureLogin();
-            const viaDsm = await fetchInstalledPackageState(dsmOrigin, cookieHeader ?? "", packageIdentity);
-            if (viaDsm) {
-                return viaDsm;
-            }
-            const result = synoagentcli(["dsm", "package-center", "get", packageIdentity], profileName);
-            if (result.status !== 0) {
-                return undefined;
-            }
-            try {
-                const parsed = JSON.parse(result.stdout);
-                return packageStateFromRecord(parsed.data);
-            }
-            catch {
-                return undefined;
-            }
-        },
-        async getInstalledPackageVersion(packageIdentity) {
-            await ensureLogin();
-            const viaDsm = await fetchInstalledPackageState(dsmOrigin, cookieHeader ?? "", packageIdentity);
-            if (viaDsm?.version) {
-                return viaDsm.version;
-            }
-            const result = synoagentcli(["dsm", "package-center", "get", packageIdentity], profileName);
-            if (result.status !== 0) {
-                return undefined;
-            }
-            try {
-                const parsed = JSON.parse(result.stdout);
-                return parsed.data?.version;
-            }
-            catch {
-                return undefined;
-            }
-        },
-        async isPackageInstalled(packageIdentity) {
-            await ensureLogin();
-            const viaDsm = await fetchInstalledPackageState(dsmOrigin, cookieHeader ?? "", packageIdentity);
-            if (viaDsm) {
-                return viaDsm.installed;
-            }
-            const result = synoagentcli(["dsm", "package-center", "get", packageIdentity], profileName);
-            return result.status === 0;
+            return fetchInstalledPackageState(dsmOrigin, cookieHeader ?? '', packageIdentity);
         },
+        async getInstalledPackageVersion(packageIdentity) { return (await this.getInstalledPackageState(packageIdentity))?.version; },
+        async isPackageInstalled(packageIdentity) { return (await this.getInstalledPackageState(packageIdentity))?.installed === true; },
         async fetchContainerLogs(packageIdentity) {
-            const result = synoagentcli(["dsm", "package-center", "status", packageIdentity], profileName);
-            if (result.status !== 0) {
-                return [];
-            }
-            return result.stdout
-                .split("\n")
-                .map((line) => line.trim())
-                .filter(Boolean)
-                .map((line) => `[status] ${line}`);
+            const state = await this.getInstalledPackageState(packageIdentity);
+            return state?.installed ? [`[status] ${state.status ?? 'unknown'} ${state.version ?? ''}`] : [];
         },
         async getDsmPortProfileInventory() {
             try {
                 await ensureLogin();
                 return await fetchDsmPortProfileInventory(dsmOrigin, cookieHeader ?? "");
             }
-            catch {
+            catch (error) {
+                if (error instanceof CtlError)
+                    throw error;
                 return undefined;
             }
         },

package/dist/host/dsm-http.d.ts

@@ -1 +1,3 @@
+import { type DsmSession } from '../ctl/transport.js';
+export declare function registerDsmSession(session: DsmSession, name: string, ca?: string, fingerprint?: string): void;
 export declare function dsmFetch(url: string, init?: RequestInit): Promise<Response>;

package/dist/host/dsm-http.js

@@ -1,3 +1,7 @@
+import { sessionFetch } from '../ctl/transport.js';
+import { CtlError } from '../ctl/errors.js';
+const sessions = new Map();
+export function registerDsmSession(session, name, ca, fingerprint) { sessions.set(session.origin + '\0' + session.cookie, { session, name, ca, fingerprint }); }
 import { spawnSync } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -39,13 +43,29 @@ function headerRecord(headers) {
 }
 export async function dsmFetch(url, init = {}) {
     try {
-        return await fetch(url, init);
+        for (const [key, value] of Object.entries(headerRecord(init.headers)))
+            if (/[\r\n\0]/.test(key + value))
+                throw new Error('Invalid header value');
+        const headers = new Headers(init.headers);
+        const binding = sessions.get(new URL(url).origin + '\0' + (headers.get('cookie') ?? ''));
+        if (binding)
+            headers.set('X-SYNO-TOKEN', binding.session.token);
+        const request = { ...init, headers, redirect: 'error', signal: init.signal ?? AbortSignal.timeout(62000) };
+        const response = binding ? await sessionFetch(url, request, binding.session, binding.ca, { fingerprint: binding.fingerprint, name: binding.name }) : await fetch(url, request);
+        if (binding && new URL(url).pathname === '/webapi/entry.cgi') {
+            const body = await response.clone().json().catch(() => null);
+            if (body?.success === false && [106, 107, 119].includes(Number(body.error?.code)))
+                throw new CtlError('CTL_NOT_AUTHENTICATED', 'DSM session expired', `run: synopkgland host login ${binding.name}`, 2);
+        }
+        return response;
     }
     catch (error) {
         const code = errorCode(error);
         if (code && UNTRUSTED_CERTIFICATE.has(code)) {
             throw untrustedCertificate(url, code);
         }
+        if (error instanceof CtlError)
+            throw error;
         if (!isHostUnreachable(error)) {
             throw error;
         }

package/dist/host/dsm-port-profile.js

@@ -1,3 +1,4 @@
+import { CtlError } from '../ctl/errors.js';
 import { basename } from "node:path";
 import { composeProjectName } from "../build-spk/resource-worker.js";
 import { dsmFetch } from "./dsm-http.js";
@@ -169,7 +170,9 @@ async function fetchJson(dsmOrigin, cookieHeader, params) {
     try {
         return await response.json();
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError)
+            throw error;
         return undefined;
     }
 }
@@ -200,7 +203,9 @@ export async function fetchDsmPortProfileInventory(dsmOrigin, cookieHeader) {
         });
         return dsmPortProfileInventoryFromPayloads(portInfoPayload, packageListPayload);
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError)
+            throw error;
         return undefined;
     }
 }

package/dist/host/install-plan.d.ts

@@ -0,0 +1,32 @@
+export interface NasTarget {
+    arch: string;
+    version: string;
+    build: number;
+    major: number;
+    minor: number;
+}
+export interface StoreEntry {
+    package: string;
+    version: string;
+    link: string;
+    size: number;
+    md5?: string;
+    sha256?: string;
+    arch?: string | string[];
+    os_min_ver?: string;
+    os_max_ver?: string;
+    deppkgs?: unknown;
+}
+export declare function compareVersions(a: string, b: string): number;
+export declare function archMatches(value: string | string[] | undefined, arch: string): boolean;
+export declare function assertCompatible(info: Record<string, string>, target: NasTarget): void;
+export declare function sourceUrl(source: string, target: NasTarget): URL;
+export declare function selectEntry(entries: StoreEntry[], id: string, version: string | undefined, target: NasTarget): StoreEntry;
+export interface Dependency {
+    id: string;
+    constraints: Record<string, string>;
+}
+export declare function dependencies(value: unknown): Dependency[];
+export declare function satisfies(version: string, dependency: Dependency): boolean;
+export declare function resolveInstallPlan(root: StoreEntry, entries: StoreEntry[], target: NasTarget, installed: Map<string, string>): StoreEntry[];
+export declare function verifyPins(bytes: Buffer, entry: Pick<StoreEntry, "size" | "md5" | "sha256">): void;

package/dist/host/install-plan.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { CtlError } from "../ctl/errors.js";
+import { familyOfArchToken } from "../build-spk/dsm-arch.js";
+const fail = (code, message, hint = "Check the package source and select a compatible package") => new CtlError(code, message, hint, 3);
+export function compareVersions(a, b) {
+    const x = a.split(/[._-]/).map(Number), y = b.split(/[._-]/).map(Number);
+    if ([...x, ...y].some((n) => !Number.isSafeInteger(n) || n < 0))
+        throw fail("PACKAGE_VERSION_INVALID", "Package versions must contain numeric segments");
+    for (let i = 0; i < Math.max(x.length, y.length); i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) - (y[i] ?? 0);
+    return 0;
+}
+export function archMatches(value, arch) {
+    if (value === undefined)
+        return true; // A DSM feed may omit arch after filtering its query.
+    const tokens = Array.isArray(value) ? value : value.split(/\s+/);
+    return tokens.some((token) => token === "noarch" || token === arch || token === familyOfArchToken(arch));
+}
+export function assertCompatible(info, target) {
+    if (!info.arch || !archMatches(info.arch, target.arch))
+        throw fail("PACKAGE_ARCH_MISMATCH", "SPK architecture does not match this NAS");
+    if (info.exclude_arch && archMatches(info.exclude_arch, target.arch))
+        throw fail("PACKAGE_ARCH_MISMATCH", "SPK excludes this NAS architecture");
+    for (const [key, side] of [
+        ["os_min_ver", -1],
+        ["os_max_ver", 1],
+    ]) {
+        if (info[key] &&
+            Math.sign(compareVersions(target.version, info[key])) === side)
+            throw fail("PACKAGE_DSM_MISMATCH", `SPK ${key} is incompatible with this NAS`);
+    }
+}
+export function sourceUrl(source, target) {
+    const url = new URL(source);
+    if (url.protocol !== "https:" || url.username || url.password)
+        throw fail("PACKAGE_SOURCE_INVALID", "Package source must be HTTPS without URL credentials");
+    for (const [key, value] of Object.entries({
+        arch: target.arch,
+        build: target.build,
+        major: target.major,
+        minor: target.minor,
+    }))
+        url.searchParams.set(key, String(value));
+    return url;
+}
+export function selectEntry(entries, id, version, target) {
+    const matching = entries
+        .filter((e) => e.package === id &&
+        (!version || e.version === version) &&
+        archMatches(e.arch, target.arch) &&
+        (!e.os_min_ver || compareVersions(target.version, e.os_min_ver) >= 0) &&
+        (!e.os_max_ver || compareVersions(target.version, e.os_max_ver) <= 0))
+        .sort((a, b) => compareVersions(b.version, a.version));
+    if (!matching.length)
+        throw fail("PACKAGE_NOT_FOUND", `No compatible store release for ${id}${version ? "@" + version : ""}`);
+    const chosen = matching[0];
+    if (matching.filter((e) => e.version === chosen.version).length !== 1)
+        throw fail("PACKAGE_SOURCE_AMBIGUOUS", "Source offers overlapping package architectures");
+    if (!Number.isSafeInteger(chosen.size) ||
+        chosen.size <= 0 ||
+        (!chosen.md5 && !chosen.sha256))
+        throw fail("PACKAGE_PIN_INVALID", "Source must pin SPK size and MD5 or SHA-256");
+    const link = new URL(chosen.link);
+    if (link.protocol !== "https:" || link.username || link.password)
+        throw fail("PACKAGE_LINK_INVALID", "SPK download must be HTTPS without URL credentials");
+    return chosen;
+}
+export function dependencies(value) {
+    if (value === undefined || value === null || value === "")
+        return [];
+    if (typeof value === "string")
+        return value
+            .trim()
+            .split(/[:\s]+/)
+            .map((part) => {
+            const match = /^([A-Za-z][A-Za-z0-9_.+-]*)(?:(>=|<=|==|=|>|<)([0-9][0-9._-]*))?$/.exec(part);
+            if (!match)
+                throw fail("PACKAGE_DEPENDENCY_INVALID", "Unsupported package dependency syntax");
+            return {
+                id: match[1],
+                constraints: match[2] ? { [match[2]]: match[3] } : {},
+            };
+        });
+    if (typeof value === "object" && !Array.isArray(value))
+        return Object.entries(value).map(([id, rules]) => {
+            if (!/^[A-Za-z][A-Za-z0-9_.+-]*$/.test(id))
+                throw fail("PACKAGE_DEPENDENCY_INVALID", "Invalid dependency package ID");
+            if (rules === null)
+                return { id, constraints: {} };
+            if (typeof rules !== "object" ||
+                Array.isArray(rules) ||
+                Object.entries(rules).some(([op, v]) => ![">=", ">", "<=", "<", "==", "="].includes(op) ||
+                    typeof v !== "string" ||
+                    !/^\d[\d._-]*$/.test(v)))
+                throw fail("PACKAGE_DEPENDENCY_INVALID", "Unsupported package dependency rules");
+            return { id, constraints: rules };
+        });
+    throw fail("PACKAGE_DEPENDENCY_INVALID", "Unsupported package dependency format");
+}
+export function satisfies(version, dependency) {
+    return Object.entries(dependency.constraints).every(([op, want]) => {
+        const c = compareVersions(version, want);
+        return op === ">="
+            ? c >= 0
+            : op === ">"
+                ? c > 0
+                : op === "<="
+                    ? c <= 0
+                    : op === "<"
+                        ? c < 0
+                        : c === 0;
+    });
+}
+export function resolveInstallPlan(root, entries, target, installed) {
+    const plan = [], visiting = new Set(), chosen = new Map();
+    const visit = (entry) => {
+        if (visiting.has(entry.package))
+            throw fail("PACKAGE_DEPENDENCY_CYCLE", "Package dependency cycle detected");
+        if (chosen.has(entry.package))
+            return;
+        visiting.add(entry.package);
+        for (const dep of dependencies(entry.deppkgs)) {
+            const existing = chosen.get(dep.id);
+            if (existing) {
+                if (!satisfies(existing.version, dep))
+                    throw fail("PACKAGE_DEPENDENCY_CONFLICT", `Conflicting dependency ${dep.id}`);
+                continue;
+            }
+            if (installed.has(dep.id) && satisfies(installed.get(dep.id), dep))
+                continue;
+            const candidates = entries.filter((e) => e.package === dep.id && satisfies(e.version, dep));
+            if (!candidates.length)
+                throw fail("PACKAGE_DEPENDENCY_REQUIRED", `Install required Synology package ${dep.id}${Object.entries(dep.constraints)
+                    .map(([k, v]) => k + v)
+                    .join(",")} first`, "Install the dependency in DSM Package Center, then retry");
+            visit(selectEntry(candidates, dep.id, undefined, target));
+        }
+        visiting.delete(entry.package);
+        chosen.set(entry.package, entry);
+        plan.push(entry);
+    };
+    visit(root);
+    return plan;
+}
+export function verifyPins(bytes, entry) {
+    if (bytes.length !== entry.size)
+        throw fail("PACKAGE_SIZE_MISMATCH", "Downloaded SPK size differs from the feed pin");
+    for (const algorithm of ["md5", "sha256"]) {
+        const pin = entry[algorithm];
+        if (pin === undefined)
+            continue;
+        if (!new RegExp(`^[a-fA-F0-9]{${algorithm === "md5" ? 32 : 64}}$`).test(pin) ||
+            createHash(algorithm).update(bytes).digest("hex") !== pin.toLowerCase())
+            throw fail("PACKAGE_DIGEST_MISMATCH", `Downloaded SPK ${algorithm.toUpperCase()} differs from the feed pin`);
+    }
+}

package/dist/host/package-commands.d.ts

@@ -0,0 +1,75 @@
+import { type NasConnection } from "./connection.js";
+import { type NasTarget, type StoreEntry } from "./install-plan.js";
+export declare const DEFAULT_PACKAGE_SOURCE = "https://packages.synopkgland.com";
+export declare function packageId(value: string): string;
+export declare function nasTarget(nas: NasConnection): Promise<NasTarget>;
+export declare function readFeed(source: string, target: NasTarget): Promise<StoreEntry[]>;
+export interface InstallOptions {
+    host?: string;
+    source?: string;
+    param?: Record<string, string>;
+    yes?: boolean;
+    dryRun?: boolean;
+}
+export declare function installPackage(spec: string, options?: InstallOptions, connection?: NasConnection): Promise<{
+    host: string;
+    target: NasTarget;
+    source: string;
+    packages: {
+        signed?: boolean | undefined;
+        package: string;
+        version: string;
+        size: number;
+        action: string;
+    }[];
+    parameters: string[];
+    dryRun: boolean;
+} | {
+    status: import("./catalog-install.js").InstalledPackageState | undefined;
+    host: string;
+    target: NasTarget;
+    source: string;
+    packages: {
+        signed?: boolean | undefined;
+        package: string;
+        version: string;
+        size: number;
+        action: string;
+    }[];
+    parameters: string[];
+}>;
+export declare function uninstallPackage(id: string, options?: {
+    host?: string;
+    yes?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    dryRun: boolean;
+    host: string;
+    package: string;
+    action: string;
+    installed?: undefined;
+} | {
+    host: string;
+    package: string;
+    installed: boolean;
+    dryRun?: undefined;
+    action?: undefined;
+}>;
+export declare function packageStatus(id: string, host?: string): Promise<{
+    installed: boolean;
+    version?: string;
+    status?: string;
+    error?: {
+        code?: number;
+        description?: string;
+        workerMsg?: unknown[];
+    };
+    brokenBy?: string;
+    stage?: string;
+    lastStage?: string;
+    statusCode?: number;
+    statusDescription?: string;
+    statusOrigin?: string;
+    host: string;
+    package: string;
+}>;