@synopackageland/cli 0.33.0 → 0.33.1

package/dist/host/dsm-http.js

@@ -1,144 +1,2 @@
-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";
-import { join } from "node:path";
-function errorCode(error) {
-    return error.cause?.code
-        ?? error.code;
-}
-function isHostUnreachable(error) {
-    const code = errorCode(error);
-    return code === "EHOSTUNREACH" || code === "ENETUNREACH";
-}
-const UNTRUSTED_CERTIFICATE = new Set([
-    "DEPTH_ZERO_SELF_SIGNED_CERT",
-    "SELF_SIGNED_CERT_IN_CHAIN",
-    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
-    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
-    "CERT_HAS_EXPIRED",
-    "ERR_TLS_CERT_ALTNAME_INVALID",
-]);
-/** Node reports an untrusted certificate only as "fetch failed"; say what to do. Verification stays on. */
-function untrustedCertificate(url, code) {
-    const origin = new URL(url).origin;
-    return Object.assign(new Error(`DSM at ${origin} presented a TLS certificate this computer does not trust (${code}). ` +
-        `Export the NAS certificate or its CA as PEM and run with NODE_EXTRA_CA_CERTS=<that file>, ` +
-        `or give DSM a certificate whose name matches the host profile. Certificate checks stay on.`), { code: "DSM_TLS_UNTRUSTED" });
-}
-function headerRecord(headers) {
-    if (!headers) {
-        return {};
-    }
-    if (headers instanceof Headers) {
-        return Object.fromEntries(headers.entries());
-    }
-    if (Array.isArray(headers)) {
-        return Object.fromEntries(headers);
-    }
-    return { ...headers };
-}
-export async function dsmFetch(url, init = {}) {
-    try {
-        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;
-        }
-        return curlFetch(url, init);
-    }
-}
-function curlConfigString(value) {
-    const escapes = { "\\": "\\\\", '"': '\\"', "\t": "\\t", "\n": "\\n", "\r": "\\r", "\v": "\\v" };
-    return `"${value.replace(/[\\"\t\n\r\v]/g, (c) => escapes[c])}"`;
-}
-async function curlFetch(url, init) {
-    const staging = mkdtempSync(join(tmpdir(), "synopkgland-dsm-http-"));
-    const headerFile = join(staging, "headers");
-    const bodyFile = join(staging, "body");
-    try {
-        const configFile = join(staging, "config");
-        const args = ["-sS", "-D", headerFile, "-o", bodyFile, "-w", "%{http_code}", "-X", init.method ?? "GET", "-K", configFile];
-        // Headers and form text go through a private config file, not argv, and
-        // form text is sent literally (curl -F would read "@file" and "<file").
-        const config = [];
-        const headers = headerRecord(init.headers);
-        for (const [name, value] of Object.entries(headers)) {
-            if (name.toLowerCase() === "content-type" && init.body instanceof FormData) {
-                continue;
-            }
-            if (/[\r\n\0]/.test(name + value)) {
-                throw new Error(`Invalid header value: ${name}`);
-            }
-            config.push(`header = ${curlConfigString(`${name}: ${value}`)}`);
-        }
-        let stdin;
-        if (init.body instanceof FormData) {
-            for (const [name, value] of init.body.entries()) {
-                if (typeof value === "string") {
-                    if (/[=\0]/.test(name) || value.includes("\0")) {
-                        throw new Error(`Invalid form field: ${name}`);
-                    }
-                    config.push(`form-string = ${curlConfigString(`${name}=${value}`)}`);
-                    continue;
-                }
-                const filename = "name" in value && typeof value.name === "string" ? value.name : "upload.bin";
-                const partPath = join(staging, filename);
-                writeFileSync(partPath, Buffer.from(await value.arrayBuffer()));
-                config.push(`form = ${curlConfigString(`${name}=@${partPath};filename=${filename}`)}`);
-            }
-        }
-        else if (typeof init.body === "string") {
-            stdin = Buffer.from(init.body);
-            args.push("--data-binary", "@-");
-        }
-        else if (init.body) {
-            stdin = Buffer.from(await new Response(init.body).arrayBuffer());
-            args.push("--data-binary", "@-");
-        }
-        writeFileSync(configFile, config.map((line) => line + "\n").join(""), { mode: 0o600 });
-        args.push(url);
-        const result = spawnSync("curl", args, { encoding: "utf8", input: stdin });
-        if (result.status !== 0) {
-            throw new Error(result.stderr || `curl exit ${result.status}`);
-        }
-        const status = Number((result.stdout ?? "").trim().slice(-3));
-        const rawHeaders = readFileSync(headerFile, "utf8");
-        const body = readFileSync(bodyFile);
-        const responseHeaders = new Headers();
-        for (const line of rawHeaders.split(/\r?\n/)) {
-            const idx = line.indexOf(":");
-            if (idx > 0) {
-                responseHeaders.append(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
-            }
-        }
-        return new Response(body, { status: Number.isInteger(status) ? status : 502, headers: responseHeaders });
-    }
-    finally {
-        rmSync(staging, { recursive: true, force: true });
-    }
-}
+// Compatibility export; every DSM request uses the shared NAS connection module.
+export { dsmFetch, registerDsmSession } from '../nas/http.js';

package/dist/host/package-commands.js

@@ -5,7 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { CtlError } from "../ctl/errors.js";
 import { inspectAnySpk } from "../spk/inspect.js";
 import { connectNas, requireAdministrator, } from "./connection.js";
-import { dsmFetch } from "./dsm-http.js";
+import { fetchPackageSource } from "../package-source.js";
 import { fetchInstalledPackageState, installPackageFromLocalSpk, uninstallPackageFromDsm, } from "./catalog-install.js";
 import { assertCompatible, sourceUrl, selectEntry, resolveInstallPlan, verifyPins, compareVersions, } from "./install-plan.js";
 export const DEFAULT_PACKAGE_SOURCE = "https://packages.synopkgland.com";
@@ -38,7 +38,7 @@ export async function nasTarget(nas) {
     return { arch, version: `${version}-${build}`, major, minor, build };
 }
 export async function readFeed(source, target) {
-    const response = await dsmFetch(sourceUrl(source, target).href);
+    const response = await fetchPackageSource(sourceUrl(source, target).href);
     if (!response.ok)
         throw fail("PACKAGE_SOURCE_FAILED", `Package source returned HTTP ${response.status}`);
     const body = (await response.json());
@@ -145,7 +145,7 @@ export async function installPackage(spec, options = {}, connection) {
         for (const entry of plan) {
             let file = localFile;
             if (!local || entry.package !== root.package) {
-                const response = await dsmFetch(entry.link);
+                const response = await fetchPackageSource(entry.link);
                 if (!response.ok)
                     throw fail("PACKAGE_DOWNLOAD_FAILED", `SPK download returned HTTP ${response.status}`);
                 const bytes = Buffer.from(await response.arrayBuffer());

package/dist/host/types.d.ts

@@ -69,6 +69,7 @@ export interface HostCredentials {
     hostName?: string;
     ca?: string;
     fingerprint?: string;
+    tls?: import("../nas/tls.js").HostTls;
     loadSession?: () => Promise<import("../ctl/transport.js").DsmSession>;
     cookieHeader?: string;
 }

package/dist/nas/auth.d.ts

@@ -0,0 +1,10 @@
+import { type DsmSession, type JsonRequest } from './transport.js';
+export interface LoginOptions {
+    remember?: boolean;
+    deviceId?: string;
+    otp: () => Promise<string>;
+    request?: JsonRequest;
+    ca?: string;
+}
+export declare function loginDsm(origin: string, username: string, password: string, options: LoginOptions): Promise<DsmSession>;
+export declare function logoutDsm(session: DsmSession, request?: JsonRequest): Promise<void>;

package/dist/nas/auth.js

@@ -0,0 +1,30 @@
+import { CtlError } from '../ctl/errors.js';
+import { createRequest } from './transport.js';
+export async function loginDsm(origin, username, password, options) {
+    const request = options.request ?? createRequest(origin, 30000, options.ca);
+    const form = new URLSearchParams({ api: 'SYNO.API.Auth', version: '7', method: 'login', account: username, passwd: password, session: 'DSM', format: 'cookie', enable_syno_token: 'yes', enable_device_token: options.remember === false ? 'no' : 'yes', device_name: 'synopkgland', device_id: options.deviceId ?? '' });
+    let result = await request('/webapi/entry.cgi', form);
+    if (result?.error?.code === 402) {
+        form.delete('session');
+        result = await request('/webapi/entry.cgi', form);
+    }
+    if (result?.error?.code === 403) {
+        const otp = await options.otp();
+        if (!/^\d{6}$/.test(otp))
+            throw new CtlError('CTL_OTP_INVALID', 'OTP must be six digits.', 'run: synopkgland host login <name>', 2);
+        form.set('otp_code', otp);
+        result = await request('/webapi/entry.cgi', form);
+    }
+    if (result?.success !== true || typeof result.data?.sid !== 'string' || !result.data.sid || typeof result.data.synotoken !== 'string' || !result.data.synotoken)
+        throw new CtlError('CTL_AUTH_FAILED', `DSM login failed (${Number(result?.error?.code) || 'invalid response'}).`, 'run: synopkgland host login <name>', 2);
+    if (/[;\r\n\x00]/.test(result.data.sid) || /[\r\n\x00]/.test(result.data.synotoken) || result.data.sid.length > 4096 || result.data.synotoken.length > 4096)
+        throw new CtlError('CTL_AUTH_FAILED', 'DSM returned invalid session carriers.', 'Check the DSM endpoint.', 2);
+    const returnedDevice = result.data.device_id || result.data.did || options.deviceId;
+    const deviceId = options.remember === false ? undefined : typeof returnedDevice === 'string' && returnedDevice.length <= 4096 && !/[\r\n\x00]/.test(returnedDevice) ? returnedDevice : undefined;
+    return { origin, username, cookie: `id=${result.data.sid}`, token: result.data.synotoken, ...(deviceId ? { deviceId } : {}) };
+}
+export async function logoutDsm(session, request = createRequest(session.origin)) {
+    const body = await request('/webapi/entry.cgi', new URLSearchParams({ api: 'SYNO.API.Auth', version: '7', method: 'logout', SynoToken: session.token }), session);
+    if (body?.success !== true)
+        throw new CtlError('CTL_LOGOUT_FAILED', 'DSM did not confirm logout.', 'Retry logout or revoke the NAS session.', 2);
+}

package/dist/nas/connection.d.ts

@@ -0,0 +1,9 @@
+import { type DsmSession, type JsonRequest } from "./transport.js";
+export interface NasConnection {
+    name: string;
+    session: DsmSession;
+    request: JsonRequest;
+    call: (api: string, method: string, version: number, params?: Record<string, string>) => Promise<any>;
+}
+export declare function connectNas(name?: string): Promise<NasConnection>;
+export declare function requireAdministrator(nas: NasConnection): Promise<void>;

package/dist/nas/connection.js

@@ -0,0 +1,46 @@
+import { CtlError } from "../ctl/errors.js";
+import { createRequest, } from "./transport.js";
+import { resolveHostCredentials } from "./credentials.js";
+import { registerDsmSession } from "./http.js";
+export async function connectNas(name) {
+    const credentials = resolveHostCredentials(name);
+    const session = await credentials.loadSession();
+    registerDsmSession(session, credentials.hostName, credentials.ca, credentials.fingerprint, credentials.tls);
+    const request = createRequest(session.origin, 62000, credentials.ca, credentials.tls);
+    return {
+        name: credentials.hostName,
+        session,
+        request,
+        call: async (api, method, version, params = {}) => {
+            const body = await request("/webapi/entry.cgi", new URLSearchParams({
+                api,
+                method,
+                version: String(version),
+                ...params,
+            }), session);
+            const code = Number(body?.error?.code);
+            if (body?.success !== true)
+                throw new CtlError([106, 107, 119].includes(code)
+                    ? "CTL_NOT_AUTHENTICATED"
+                    : code === 105
+                        ? "NAS_ADMIN_REQUIRED"
+                        : "DSM_API_FAILED", `DSM ${api}/${method} failed (${code || "invalid response"})`, [106, 107, 119].includes(code)
+                    ? `run: synopkgland host login ${credentials.hostName}`
+                    : code === 105
+                        ? "Log in with a DSM administrator account"
+                        : "Check DSM permissions and Package Center", 2);
+            return body.data;
+        },
+    };
+}
+export async function requireAdministrator(nas) {
+    const data = await nas.call("SYNO.Core.Group.Member", "list", 1, {
+        group: "administrators",
+        offset: "0",
+        limit: "-1",
+    });
+    const members = data?.users;
+    if (!Array.isArray(members) ||
+        !members.some((u) => u.name === nas.session.username))
+        throw new CtlError("NAS_ADMIN_REQUIRED", "Package installation and removal require a DSM administrator account", "Register and log in with a DSM administrator account", 4);
+}

package/dist/nas/credentials.d.ts

@@ -0,0 +1,6 @@
+import { CtlStore } from "./store.js";
+import type { HostCredentials } from "../host/types.js";
+/** Host metadata is public; session carriers are loaded only from secure storage. */
+export declare function resolveHostCredentials(name?: string, store?: CtlStore): HostCredentials | null;
+/** Legacy embedded callers supply credentials here too; there is only one DSM login implementation. */
+export declare function sessionForCredentials(credentials: HostCredentials): Promise<import("./transport.js").DsmSession>;

package/dist/nas/credentials.js

@@ -0,0 +1,22 @@
+import { registerDsmSession } from "./http.js";
+import { CtlStore } from "./store.js";
+import { loginDsm } from "./auth.js";
+/** Host metadata is public; session carriers are loaded only from secure storage. */
+export function resolveHostCredentials(name, store = new CtlStore()) {
+    const host = store.select(name);
+    return {
+        dsmOrigin: host.origin,
+        username: host.username,
+        hostName: host.name,
+        fingerprint: host.fingerprint,
+        ca: store.trust(host).ca,
+        tls: store.trust(host),
+        loadSession: async () => { const session = await store.session(host); registerDsmSession(session, host.name, undefined, undefined, store.trust(host)); return session; },
+    };
+}
+/** Legacy embedded callers supply credentials here too; there is only one DSM login implementation. */
+export async function sessionForCredentials(credentials) {
+    const session = credentials.loadSession ? await credentials.loadSession() : await loginDsm(credentials.dsmOrigin, credentials.username, credentials.password ?? '', { remember: false, otp: async () => process.env.DSM_OTP ?? '' });
+    registerDsmSession(session, credentials.hostName ?? 'env', credentials.ca, credentials.fingerprint, credentials.tls);
+    return session;
+}

package/dist/nas/http.d.ts

@@ -0,0 +1,5 @@
+import { type DsmSession } from './transport.js';
+import type { HostTls } from './tls.js';
+export declare function registerDsmSession(session: DsmSession, name: string, ca?: string, fingerprint?: string, policy?: HostTls): void;
+/** All DSM fetch callers, including session-only automation, use the NAS socket policy. */
+export declare function dsmFetch(url: string, init?: RequestInit): Promise<Response>;

package/dist/nas/http.js

@@ -0,0 +1,25 @@
+import { sessionFetch } from './transport.js';
+import { assertSessionActive } from './session.js';
+import { CtlError } from '../ctl/errors.js';
+const bindings = new Map();
+const policies = new Map();
+export function registerDsmSession(session, name, ca, fingerprint, policy) {
+    const trust = policy ?? { name, ca, fingerprint };
+    bindings.set(session.origin + '\0' + session.cookie, { session, name, trust });
+    policies.set(session.origin, trust);
+}
+/** All DSM fetch callers, including session-only automation, use the NAS socket policy. */
+export async function dsmFetch(url, init = {}) {
+    const headers = new Headers(init.headers), origin = new URL(url).origin;
+    const cookie = headers.get('cookie') ?? '';
+    // App cookies can accompany a DSM cookie; keep its token and TLS policy.
+    const binding = [...bindings.values()].find(b => b.session.origin === origin && cookie.split(/;\s*/).includes(b.session.cookie));
+    const response = await sessionFetch(url, { ...init, headers }, binding ? { ...binding.session, cookie } : undefined, undefined, binding?.trust ?? policies.get(origin));
+    if (response.status >= 300 && response.status < 400)
+        throw new CtlError('CTL_HTTP_ERROR', `HTTP ${response.status}; redirects are never followed`, 'Check the NAS URL', 6);
+    if (binding && new URL(url).pathname === '/webapi/entry.cgi') {
+        const body = await response.clone().json().catch(() => null);
+        assertSessionActive(body, binding.name);
+    }
+    return response;
+}

package/dist/nas/options.d.ts

@@ -0,0 +1,13 @@
+export interface NasOptions {
+    strictTls?: boolean;
+    ca?: string;
+    url?: string;
+    warn?: (line: string) => void;
+}
+export declare const nasOptions: () => NasOptions;
+export declare function withNasOptions<T>(options: NasOptions, run: () => T): T;
+/** Shared flag extraction for ctl and ordinary commands; overrides last for this invocation only. */
+export declare function nasFlags(argv: string[], allowUrl?: boolean): {
+    args: string[];
+    options: NasOptions;
+};

package/dist/nas/options.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { CtlError } from '../ctl/errors.js';
+const context = new AsyncLocalStorage();
+export const nasOptions = () => context.getStore() ?? {};
+export function withNasOptions(options, run) {
+    return context.run({ ...nasOptions(), ...options }, run);
+}
+/** Shared flag extraction for ctl and ordinary commands; overrides last for this invocation only. */
+export function nasFlags(argv, allowUrl = false) {
+    const args = [...argv], options = {};
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === '--strict-tls') {
+            options.strictTls = true;
+            args.splice(i--, 1);
+        }
+        else if (allowUrl && (flag === '--url' || flag.startsWith('--url=')) && args[0] !== 'host' && args[2] !== 'host') {
+            const value = flag.includes('=') ? flag.slice(6) : args[i + 1];
+            if (!value || value.startsWith('--'))
+                throw new CtlError('CTL_ARGUMENT_INVALID', '--url requires a NAS origin', 'Use --url https://<nas>:5001');
+            options.url = value;
+            args.splice(i--, flag.includes('=') ? 1 : 2);
+        }
+        else if (flag === '--ca' || flag.startsWith('--ca=')) {
+            const value = flag.includes('=') ? flag.slice(5) : args[i + 1];
+            if (!value || value.startsWith('--'))
+                throw new CtlError('CTL_ARGUMENT_INVALID', '--ca requires a PEM file', 'Use --ca <file>');
+            options.ca = value;
+            args.splice(i--, flag.includes('=') ? 1 : 2);
+        }
+    }
+    return { args, options };
+}

package/dist/nas/session.d.ts

@@ -0,0 +1,2 @@
+/** Passwords are never persisted. Expired sessions require login; writes are never replayed. */
+export declare function assertSessionActive(body: any, name?: string): void;

package/dist/nas/session.js

@@ -0,0 +1,6 @@
+import { CtlError } from '../ctl/errors.js';
+/** Passwords are never persisted. Expired sessions require login; writes are never replayed. */
+export function assertSessionActive(body, name = '<name>') {
+    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 ${name}`, 2);
+}

package/dist/nas/store.d.ts

@@ -0,0 +1,61 @@
+import type { DsmSession } from './transport.js';
+import type { HostTls } from './tls.js';
+export interface Approval {
+    version: string;
+    hash?: string;
+}
+export interface Host {
+    name: string;
+    origin: string;
+    username: string;
+    fingerprint?: string;
+    strictTls?: boolean;
+    ephemeral?: boolean;
+    tunnel?: boolean;
+    ca?: string;
+    lastUsed?: string;
+    approved: Record<string, Approval>;
+}
+export interface CredentialStore {
+    get(key: string): Promise<DsmSession | null>;
+    set(key: string, value: DsmSession): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare class OsCredentialStore implements CredentialStore {
+    private entry;
+    get(key: string): Promise<DsmSession | null>;
+    set(key: string, value: DsmSession): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare class CtlStore {
+    root: string;
+    credentials: CredentialStore;
+    constructor(root?: string, credentials?: CredentialStore);
+    private safe;
+    private file;
+    key(host: Host): string;
+    defaultName(): string | undefined;
+    setDefault(name: string): void;
+    automation(): Host | undefined;
+    targets(): Host[];
+    select(name?: string): Host;
+    list(): Host[];
+    get(name: string): Host;
+    save(host: Host): void;
+    add(host: Host, session: DsmSession): Promise<void>;
+    trust(host: Host): HostTls;
+    session(host: Host): Promise<DsmSession>;
+    cacheRoot(host: Host): string;
+    cacheFile(host: Host, pkg: string, version: string): string;
+    cache(host: Host, pkg: string, version: string): any | null;
+    putCache(host: Host, pkg: string, version: string, description: any): void;
+    putFailure(host: Host, pkg: string, version: string, failure: unknown): void;
+    revoke(name: string, pkg: string): {
+        revoked: string;
+        cacheCleared: boolean;
+    };
+    remove(name: string): Promise<{
+        removed: string;
+        deleted: string[];
+    }>;
+}

package/dist/nas/store.js

@@ -0,0 +1,144 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, rmSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { CtlError, choose } from '../ctl/errors.js';
+import { loginDsm } from './auth.js';
+import { createRequest, canonicalOrigin } from './transport.js';
+import { nasOptions } from './options.js';
+import { publicDescriptor } from '../ctl/redaction.js';
+export class OsCredentialStore {
+    async entry(key) { try {
+        const { AsyncEntry } = await import('@napi-rs/keyring');
+        return new AsyncEntry('synopkgland.ctl', key, { linux: { store: 'secret-service' } });
+    }
+    catch {
+        throw new CtlError('CTL_CREDENTIAL_STORE', 'OS secure credential store unavailable.', 'Unlock the OS credential store and retry.', 2);
+    } }
+    async get(key) { try {
+        const raw = await (await this.entry(key)).getPassword();
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch (e) {
+        if (e instanceof CtlError)
+            throw e;
+        throw new CtlError('CTL_CREDENTIAL_STORE', 'Cannot read OS credentials.', 'Unlock the OS credential store and retry.', 2);
+    } }
+    async set(key, value) { try {
+        await (await this.entry(key)).setPassword(JSON.stringify(value));
+    }
+    catch {
+        throw new CtlError('CTL_CREDENTIAL_STORE', 'Cannot save session in OS secure storage.', 'Unlock the OS credential store and retry.', 2);
+    } }
+    async delete(key) { try {
+        await (await this.entry(key)).deleteCredential();
+    }
+    catch {
+        throw new CtlError('CTL_CREDENTIAL_STORE', 'Cannot remove OS credentials.', 'Unlock the OS credential store and retry removal.', 2);
+    } }
+}
+export class CtlStore {
+    root;
+    credentials;
+    constructor(root = process.env.SYNOPKGLAND_CTL_DIR ?? join(homedir(), '.synopkgland', 'ctl'), credentials = new OsCredentialStore()) {
+        this.root = root;
+        this.credentials = credentials;
+    }
+    safe(name) { if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name))
+        throw new CtlError('CTL_HOST_INVALID', 'Invalid host name.', 'Use letters, digits, dots, dashes or underscores.'); return name; }
+    file(name) { return join(this.root, 'hosts', this.safe(name) + '.json'); }
+    key(host) { return createHash('sha256').update(host.name + '\0' + host.origin + '\0' + host.username).digest('hex'); }
+    defaultName() { try {
+        return JSON.parse(readFileSync(join(this.root, 'default.json'), 'utf8')).name;
+    }
+    catch {
+        return undefined;
+    } }
+    setDefault(name) { this.get(name); mkdirSync(this.root, { recursive: true, mode: 0o700 }); const file = join(this.root, 'default.json'), temp = file + '.' + randomUUID(); writeFileSync(temp, JSON.stringify({ name }), { mode: 0o600 }); renameSync(temp, file); }
+    automation() {
+        const url = nasOptions().url ?? process.env.DSM_URL;
+        if (url && process.env.DSM_USERNAME && process.env.DSM_PASSWORD)
+            return { name: 'env', origin: canonicalOrigin(url), username: process.env.DSM_USERNAME, approved: {}, ephemeral: true };
+    }
+    targets() { const registered = this.list(); const ephemeral = this.automation(); return ephemeral && (nasOptions().url || !registered.length) ? [ephemeral] : registered; }
+    select(name) { if (!name) {
+        const ephemeral = this.automation();
+        if (ephemeral && (nasOptions().url || !this.list().length))
+            return ephemeral;
+    } if (name)
+        return this.get(name); const hosts = this.list(); const selected = this.defaultName(); if (selected)
+        return this.get(selected); if (hosts.length === 1)
+        return hosts[0]; throw new CtlError('CTL_HOST_REQUIRED', hosts.length ? 'Choose a NAS with --host.' : 'No NAS hosts registered.', hosts.length ? 'run: synopkgland host default <name>' : 'run: synopkgland host add <name> --url https://<nas>:5001', 2); }
+    list() { const dir = join(this.root, 'hosts'); if (!existsSync(dir))
+        return []; return readdirSync(dir).filter(n => n.endsWith('.json')).map(n => JSON.parse(readFileSync(join(dir, n), 'utf8'))).sort((a, b) => a.name.localeCompare(b.name)); }
+    get(name) { this.safe(name); const host = this.list().find(h => h.name === name); if (!host)
+        return choose(name, this.list().map(h => h.name), 'host'); return host; }
+    save(host) { if (host.ephemeral)
+        return; const file = this.file(host.name); mkdirSync(join(this.root, 'hosts'), { recursive: true, mode: 0o700 }); const temp = file + '.' + randomUUID(); writeFileSync(temp, JSON.stringify(host), { mode: 0o600 }); renameSync(temp, file); chmodSync(file, 0o600); }
+    async add(host, session) { if (this.list().some(h => h.name === host.name))
+        throw new CtlError('CTL_HOST_EXISTS', 'Host name already registered.', `run: synopkgland host login ${host.name}`); await this.credentials.set(this.key(host), session); try {
+        this.save(host);
+    }
+    catch (e) {
+        await this.credentials.delete(this.key(host));
+        throw e;
+    } }
+    trust(host) {
+        const override = nasOptions();
+        return { name: host.name, fingerprint: host.fingerprint, strictTls: host.strictTls || override.strictTls, ca: (override.ca ?? host.ca) ? readFileSync((override.ca ?? host.ca), 'utf8') : undefined,
+            readFingerprint: () => { try {
+                return JSON.parse(readFileSync(this.file(host.name), 'utf8')).fingerprint;
+            }
+            catch {
+                return host.fingerprint;
+            } },
+            record: (fingerprint) => { host.fingerprint = fingerprint; this.save(host); }, warn: override.warn };
+    }
+    async session(host) {
+        let session;
+        if (process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
+            if (process.env.DSM_USERNAME !== host.username)
+                throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Automation account differs from the registered host.', 'Use the registered account or a separately named host.', 2);
+            session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, 30000, undefined, this.trust(host)) });
+        }
+        else
+            session = await this.credentials.get(this.key(host));
+        if (!session?.cookie || !session.token)
+            throw new CtlError('CTL_NOT_AUTHENTICATED', `Host ${host.name} is not logged in.`, `run: synopkgland host login ${host.name}`, 2);
+        if (/[\r\n\0]/.test(session.cookie + session.token))
+            throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Stored session carriers are invalid', `run: synopkgland host login ${host.name}`, 2);
+        if (session.origin !== host.origin || session.username !== host.username)
+            throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Stored credentials do not match host.', 'Run synopkgland host login again.', 2);
+        return session;
+    }
+    cacheRoot(host) { return join(this.root, 'cache', this.key(host)); }
+    cacheFile(host, pkg, version) { return join(this.cacheRoot(host), createHash('sha256').update(pkg + '\0' + version).digest('hex') + '.json'); }
+    cache(host, pkg, version) {
+        try {
+            const entry = JSON.parse(readFileSync(this.cacheFile(host, pkg, version), 'utf8'));
+            if (entry.description && !entry.redacted) {
+                const safe = publicDescriptor(entry.description);
+                if (JSON.stringify(safe) !== JSON.stringify(entry.description)) {
+                    this.putCache(host, pkg, version, entry.description);
+                    return { ...entry, description: safe, redacted: true };
+                }
+            }
+            return entry;
+        }
+        catch {
+            return null;
+        }
+    }
+    putCache(host, pkg, version, description) {
+        const safe = publicDescriptor(description);
+        const redacted = JSON.stringify(safe) !== JSON.stringify(description);
+        mkdirSync(this.cacheRoot(host), { recursive: true, mode: 0o700 });
+        const file = this.cacheFile(host, pkg, version), tmp = file + '.' + randomUUID();
+        writeFileSync(tmp, JSON.stringify({ hash: description.sha256, description: safe, ...(redacted ? { redacted: true } : {}) }), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    putFailure(host, pkg, version, failure) { mkdirSync(this.cacheRoot(host), { recursive: true, mode: 0o700 }); const file = this.cacheFile(host, pkg, version), tmp = file + '.' + randomUUID(); writeFileSync(tmp, JSON.stringify({ failure }), { mode: 0o600 }); renameSync(tmp, file); }
+    revoke(name, pkg) { const host = this.get(name); delete host.approved[pkg]; this.save(host); rmSync(this.cacheRoot(host), { recursive: true, force: true }); return { revoked: pkg, cacheCleared: true }; }
+    async remove(name) { const host = this.get(name); await this.credentials.delete(this.key(host)); rmSync(this.cacheRoot(host), { recursive: true, force: true }); rmSync(this.file(name)); if (this.defaultName() === name)
+        rmSync(join(this.root, 'default.json'), { force: true }); return { removed: name, deleted: ['session', 'SynoToken', 'device token', 'App approvals', 'hash pins', 'list cache', 'host registration'] }; }
+}

package/dist/nas/tls.d.ts

@@ -0,0 +1,25 @@
+import https from "node:https";
+import { CtlError } from "../ctl/errors.js";
+export interface HostTls {
+    fingerprint?: string;
+    name?: string;
+    ca?: string;
+    strictTls?: boolean;
+    expectedFingerprint?: string;
+    readFingerprint?: () => string | undefined;
+    record?: (fingerprint: string) => void;
+    warn?: (line: string) => void;
+}
+export declare function normalizeFingerprint(value: string): string;
+export declare function networkError(error: unknown): CtlError;
+export declare function timeoutError(): CtlError;
+/** TLS-only handshake. No HTTP headers, password or session is sent during discovery. */
+export declare function probeCertificate(origin: string, options?: HostTls & {
+    timeoutMs?: number;
+}): Promise<{
+    fingerprint?: string;
+    leafFingerprint?: string;
+    trusted: boolean;
+}>;
+/** Inspect the certificate and apply NAS policy before releasing this exact socket to HTTP. */
+export declare function pinnedAgent(origin: string, trust: HostTls, timeoutMs: number): https.Agent;