@synopackageland/cli 0.32.1 → 0.33.1

package/dist/host/share-permission-lookup.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { CtlError } from '../ctl/errors.js';
 const SHARE_PERMISSION_OPERATION = "SYNO_Core_Share_Permission_list_v1";
 const GROUP_LIST_OPERATION = "SYNO_Core_Group_list_v1";
 const GROUP_MEMBER_OPERATION = "SYNO_Core_Group_Member_list_v1";
@@ -8,7 +8,7 @@ function asRecord(value) {
     }
     return undefined;
 }
-/** Unwrap the synoagentcli envelope down to the DSM `data` object. */
+/** Unwrap the CLI envelope down to the DSM `data` object. */
 function dsmData(payload) {
     const outer = asRecord(payload);
     if (!outer || outer.success === false) {
@@ -77,7 +77,9 @@ export async function fetchSharePermissions(shareName, call) {
                 limit: "-1",
             }));
         }
-        catch {
+        catch (error) {
+            if (error instanceof CtlError)
+                throw error;
             return undefined;
         }
     };
@@ -94,7 +96,9 @@ export async function fetchUserGroups(userName, call) {
     try {
         groupNames = parseGroupNames(await call(GROUP_LIST_OPERATION, { offset: "0", limit: "-1" }));
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError)
+            throw error;
         return undefined;
     }
     if (!groupNames) {
@@ -106,7 +110,9 @@ export async function fetchUserGroups(userName, call) {
         try {
             members = parseGroupMemberNames(await call(GROUP_MEMBER_OPERATION, { group: groupName, offset: "0", limit: "-1" }));
         }
-        catch {
+        catch (error) {
+            if (error instanceof CtlError)
+                throw error;
             return undefined;
         }
         // One unreadable group could be the one that grants access, so a partial
@@ -120,30 +126,12 @@ export async function fetchUserGroups(userName, call) {
     }
     return memberships;
 }
-/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
-export function createSynoagentcliApiCall(profileName) {
-    return async (operationId, params) => {
-        const args = ["api", "call", "--operation-id", operationId];
-        for (const [key, value] of Object.entries(params)) {
-            args.push("--param", `${key}=${value}`);
-        }
-        if (profileName) {
-            args.push("--host", profileName);
-        }
-        const result = spawnSync("synoagentcli", args, { encoding: "utf8" });
-        if (result.status !== 0) {
-            return undefined;
-        }
-        // synoagentcli may prepend an update notice before the JSON body.
-        const match = /\{[\s\S]*\}/.exec(result.stdout ?? "");
-        if (!match) {
-            return undefined;
-        }
-        try {
-            return JSON.parse(match[0]);
-        }
-        catch {
-            return undefined;
-        }
+/** Adapt fixed operation IDs to direct DSM WebAPI requests. */
+export function createDsmApiCall(call) {
+    return async (operation, params) => {
+        const match = /^(SYNO_Core_(?:Share_Permission|Group|Group_Member))_(list)_v(1)$/.exec(operation);
+        if (!match)
+            throw new Error('Unsupported DSM read operation');
+        return { success: true, data: { response: await call(match[1].replaceAll('_', '.'), match[2], Number(match[3]), params) } };
     };
 }

package/dist/host/types.d.ts

@@ -65,6 +65,11 @@ export interface NasHost {
 export interface HostCredentials {
     dsmOrigin: string;
     username: string;
-    password: string;
+    password?: string;
+    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;