@synopackageland/cli 0.13.1 → 0.15.0

package/dist/ctl/redaction.js

@@ -0,0 +1,198 @@
+import { CtlError, ctlError } from './errors.js';
+export const REDACTED = '<redacted>';
+function reference(root, ref) {
+    if (!ref.startsWith('#'))
+        return undefined;
+    if (ref === '#')
+        return root;
+    if (ref.startsWith('#/')) {
+        let node = root;
+        for (const part of decodeURIComponent(ref.slice(2)).split('/')) {
+            const key = part.replaceAll('~1', '/').replaceAll('~0', '~');
+            if (!node || typeof node !== 'object' || !Object.hasOwn(node, key))
+                return undefined;
+            node = node[key];
+        }
+        return node;
+    }
+    const anchor = decodeURIComponent(ref.slice(1));
+    const find = (node) => {
+        if (!node || typeof node !== 'object')
+            return undefined;
+        if (node.$anchor === anchor || node.$dynamicAnchor === anchor)
+            return node;
+        for (const child of Object.values(node)) {
+            const found = find(child);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    return find(root);
+}
+// Privacy annotations from every possible branch apply conservatively, without
+// selecting a branch using secret data or mutating the schema used for validation.
+function branches(schemas, root) {
+    const result = [], seen = new Set();
+    const visit = (schema) => {
+        if (!schema || typeof schema !== 'object' || seen.has(schema))
+            return;
+        seen.add(schema);
+        result.push(schema);
+        for (const key of ['$ref', '$dynamicRef'])
+            if (typeof schema[key] === 'string')
+                visit(reference(root, schema[key]));
+        for (const key of ['allOf', 'anyOf', 'oneOf'])
+            for (const child of schema[key] ?? [])
+                visit(child);
+        for (const key of ['if', 'then', 'else', 'not'])
+            visit(schema[key]);
+        for (const child of Object.values(schema.dependentSchemas ?? {}))
+            visit(child);
+    };
+    for (const schema of schemas)
+        visit(schema);
+    return result;
+}
+export function redactValue(value, schema, root = schema, onSecret) {
+    const walk = (input, schemas) => {
+        const nodes = branches(schemas, root);
+        if (nodes.some(node => node.writeOnly === true)) {
+            onSecret?.(input);
+            return REDACTED;
+        }
+        if (Array.isArray(input))
+            return input.map((item, index) => walk(item, nodes.flatMap(node => {
+                const tuple = node.prefixItems ?? (Array.isArray(node.items) ? node.items : []);
+                return [tuple[index] ?? (!Array.isArray(node.items) ? node.items : node.additionalItems), node.contains, node.unevaluatedItems];
+            })));
+        if (input && typeof input === 'object')
+            return Object.fromEntries(Object.entries(input).map(([key, item]) => {
+                const children = [];
+                for (const node of nodes) {
+                    let matched = false;
+                    if (Object.hasOwn(node.properties ?? {}, key)) {
+                        children.push(node.properties[key]);
+                        matched = true;
+                    }
+                    for (const [pattern, child] of Object.entries(node.patternProperties ?? {})) {
+                        if (new RegExp(pattern).test(key)) {
+                            children.push(child);
+                            matched = true;
+                        }
+                    }
+                    if (!matched)
+                        children.push(node.additionalProperties);
+                    children.push(node.unevaluatedProperties);
+                }
+                return [key, walk(item, children)];
+            }));
+        return input;
+    };
+    return walk(value, [schema]);
+}
+function publicSchema(schema, root = schema) {
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    const copy = { ...schema };
+    // Schema maps are distinct from schemas: a parameter named "default" or
+    // "examples" is not the corresponding JSON Schema annotation keyword.
+    for (const key of ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas']) {
+        if (schema[key] && typeof schema[key] === 'object')
+            copy[key] = Object.fromEntries(Object.entries(schema[key]).map(([name, child]) => [name, publicSchema(child, root)]));
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+        if (Array.isArray(schema[key]))
+            copy[key] = schema[key].map((child) => publicSchema(child, root));
+    }
+    for (const key of ['items', 'additionalItems', 'contains', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'propertyNames', 'if', 'then', 'else', 'not', 'contentSchema']) {
+        if (Object.hasOwn(schema, key))
+            copy[key] = Array.isArray(schema[key])
+                ? schema[key].map((child) => publicSchema(child, root)) : publicSchema(schema[key], root);
+    }
+    for (const key of ['default', 'const'])
+        if (Object.hasOwn(schema, key))
+            copy[key] = redactValue(schema[key], schema, root);
+    for (const key of ['examples', 'enum'])
+        if (Array.isArray(schema[key]))
+            copy[key] = schema[key].map((value) => redactValue(value, schema, root));
+    return copy;
+}
+export function publicOperation(operation) {
+    return { ...operation,
+        ...(operation.paramsSchema ? { paramsSchema: publicSchema(operation.paramsSchema) } : {}),
+        ...(operation.resultSchema ? { resultSchema: publicSchema(operation.resultSchema) } : {}),
+        ...(operation.examples ? { examples: operation.examples.map(value => redactValue(value, operation.paramsSchema)) } : {}), };
+}
+export function publicDescriptor(description) {
+    if (!description?.payload?.commands)
+        return description;
+    return { ...description, payload: { ...description.payload,
+            commands: Object.fromEntries(Object.entries(description.payload.commands).map(([id, operation]) => [id, publicOperation(operation)])),
+        } };
+}
+// Redact copies of known secret values even when an App repeats them in a result
+// under another key, a job ID, or an error string. Requests keep their originals.
+export class SensitiveOutput {
+    secrets = new Set();
+    constructor(params, schema) { redactValue(params, schema, schema, value => this.remember(value)); }
+    remember(value) {
+        if (typeof value === 'string') {
+            if (!value || value === REDACTED)
+                return;
+            this.secrets.add(value);
+            this.secrets.add(encodeURIComponent(value));
+            try {
+                const url = new URL(value);
+                if (['http:', 'https:'].includes(url.protocol)) {
+                    for (const part of [url.username, url.password, ...url.searchParams.values()])
+                        if (part)
+                            this.secrets.add(part);
+                }
+            }
+            catch { /* Not a URL. */ }
+        }
+        else if (value && typeof value === 'object') {
+            for (const [key, child] of Object.entries(value)) {
+                if (!Array.isArray(value))
+                    this.remember(key);
+                this.remember(child);
+            }
+        }
+        else if (value !== undefined && value !== null)
+            this.secrets.add(String(value));
+    }
+    clean(value, schema) {
+        const redacted = redactValue(value, schema, schema, secret => this.remember(secret));
+        const secrets = [...this.secrets].sort((a, b) => b.length - a.length);
+        const text = (input) => {
+            if (input === REDACTED)
+                return input;
+            // Keep replacements separate from remaining text. This also handles large
+            // upload/base64 values without compiling them into a regular expression.
+            let parts = [input];
+            for (const secret of secrets)
+                parts = parts.flatMap(part => {
+                    if (part === null)
+                        return [null];
+                    return part.split(secret).flatMap((chunk, index) => index ? [null, chunk] : [chunk]);
+                });
+            return parts.map(part => part === null ? REDACTED : part).join('');
+        };
+        const walk = (input) => {
+            if (typeof input === 'string')
+                return text(input);
+            if (Array.isArray(input))
+                return input.map(walk);
+            if (input && typeof input === 'object')
+                return Object.fromEntries(Object.entries(input).map(([key, child]) => [this.secrets.has(key) ? REDACTED : key, walk(child)]));
+            return input !== null && this.secrets.has(String(input)) ? REDACTED : input;
+        };
+        return walk(redacted);
+    }
+    error(error) {
+        const original = ctlError(error);
+        const safe = this.clean({ message: original.message, hint: original.hint, allowed: original.allowed, plan: original.plan });
+        return new CtlError(original.code, safe.message, safe.hint, original.exitCode, safe.allowed, safe.plan);
+    }
+}

package/dist/ctl/service.d.ts

@@ -0,0 +1,38 @@
+import { type DsmSession, type JsonRequest } from './transport.js';
+import { CtlStore, type Host } from './store.js';
+import { type Descriptor } from './descriptor.js';
+export declare function boundedMap<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+export interface DiscoverOptions {
+    refresh?: boolean;
+    app?: string;
+    approve?: boolean;
+    confirm?: (packages: {
+        id: string;
+        version: string;
+    }[]) => Promise<boolean>;
+}
+export declare class CtlClient {
+    store: CtlStore;
+    host: Host;
+    request: JsonRequest;
+    constructor(store: CtlStore, host: Host, request?: JsonRequest);
+    valid(): Promise<boolean>;
+    inventory(session: DsmSession): Promise<{
+        id: string;
+        version: string;
+        state?: unknown;
+    }[]>;
+    discover(options?: DiscoverOptions): Promise<{
+        apps: Descriptor[];
+        diagnostics: any[];
+        cacheHits: number;
+    }>;
+    execute(name: string, path: string[], args: string[], options?: DiscoverOptions & {
+        yes?: boolean;
+        dryRun?: boolean;
+        stdin?: string;
+        wait?: boolean;
+        timeoutMs?: number;
+    }): Promise<any>;
+    private appCookieSession;
+}

package/dist/ctl/service.js

@@ -0,0 +1,156 @@
+import { readFileSync } from 'node:fs';
+import { CtlError, errorData, choose } from './errors.js';
+import { APP_COOKIE, createRequest } from './transport.js';
+import { DESCRIPTION_METHOD, validateDescriptor, ajv } from './descriptor.js';
+import { runFlow } from './flows.js';
+import { SensitiveOutput } from './redaction.js';
+import { localFile, transferRequest } from './transfers.js';
+import { selectApp, selectOperation, operationInput, requestPlan, confirmOperation } from './input.js';
+export async function boundedMap(items, limit, fn) { const output = new Array(items.length); let next = 0; await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => { while (next < items.length) {
+    const index = next++;
+    output[index] = await fn(items[index]);
+} })); return output; }
+export class CtlClient {
+    store;
+    host;
+    request;
+    constructor(store, host, request) {
+        this.store = store;
+        this.host = host;
+        this.request = request ?? createRequest(host.origin, 10000, host.ca ? readFileSync(host.ca, 'utf8') : undefined);
+    }
+    async valid() { try {
+        await this.inventory(await this.store.session(this.host));
+        return true;
+    }
+    catch {
+        return false;
+    } }
+    async inventory(session) {
+        const response = await this.request('/webapi/entry.cgi', new URLSearchParams({ api: 'SYNO.Core.Package', version: '2', method: 'list', additional: '["status"]', SynoToken: session.token }), session);
+        if (response?.success !== true) {
+            const code = Number(response?.error?.code);
+            throw new CtlError([106, 107, 119].includes(code) ? 'CTL_NOT_AUTHENTICATED' : 'CTL_INVENTORY_DENIED', `DSM Package list failed (${code}).`, `run: synopkgland ctl host login ${this.host.name}`, [106, 107, 119].includes(code) ? 2 : 4);
+        }
+        const entries = response.data?.packages;
+        if (!Array.isArray(entries) || response.data.total !== entries.length || entries.length > 4096)
+            throw new CtlError('CTL_INVENTORY_INVALID', 'Incomplete installed-package inventory.', 'Check the DSM version and permissions.', 5);
+        return entries.map((p) => { if (typeof p.id !== 'string' || !/^[A-Za-z][A-Za-z0-9_.+-]{0,127}$/.test(p.id) || typeof p.version !== 'string')
+            throw new CtlError('CTL_INVENTORY_INVALID', 'Invalid package identity.', 'Check the DSM response.', 5); return { id: p.id, version: p.version, state: p.additional?.status }; });
+    }
+    async discover(options = {}) {
+        const session = await this.store.session(this.host);
+        let packages = await this.inventory(session);
+        // An exact package filter narrows credential delivery. Alias selection needs the cached descriptors first.
+        if (options.app) {
+            const exact = packages.find(p => p.id.toLowerCase() === options.app.toLowerCase());
+            if (exact)
+                packages = [exact];
+            else {
+                const match = packages.find(p => this.store.cache(this.host, p.id, p.version)?.description?.payload.aliases?.some((a) => a.toLowerCase() === options.app.toLowerCase()));
+                if (match)
+                    packages = [match];
+                else {
+                    const known = packages.flatMap(p => { const d = this.store.cache(this.host, p.id, p.version)?.description; return d ? [p.id, ...d.payload.aliases] : []; });
+                    choose(options.app, known, 'app');
+                }
+            }
+        }
+        const pending = packages.filter(p => this.host.approved[p.id]?.version !== p.version);
+        if (pending.length && (options.approve || await options.confirm?.(pending))) {
+            for (const p of pending)
+                this.host.approved[p.id] = { version: p.version };
+            this.store.save(this.host);
+        }
+        let cacheHits = 0;
+        const results = await boundedMap(packages, 4, async (pkg) => {
+            const approval = this.host.approved[pkg.id];
+            if (approval?.version !== pkg.version)
+                return { error: { package: pkg.id, code: 'CTL_TRUST_REQUIRED', message: 'Description endpoint not approved.', hint: `run: synopkgland ctl list --host ${this.host.name} --approve-installed` } };
+            const cached = options.refresh ? null : this.store.cache(this.host, pkg.id, pkg.version);
+            if (cached?.failure) {
+                cacheHits++;
+                return { error: { package: pkg.id, ...cached.failure, cached: true } };
+            }
+            try {
+                let description;
+                if (cached?.description && !cached.redacted) {
+                    description = validateDescriptor(cached.description, pkg.id, pkg.version);
+                    cacheHits++;
+                }
+                else {
+                    const response = await this.request(`/webman/3rdparty/${pkg.id}/cgi/api.cgi`, { method: DESCRIPTION_METHOD, params: {} }, session);
+                    if (response?.success !== true)
+                        throw new CtlError('CTL_DESCRIPTION_UNAVAILABLE', `Description refused (${String(response?.error?.code ?? 'invalid response')}).`, 'Use --refresh after updating the App.', 5);
+                    description = validateDescriptor(response.data, pkg.id, pkg.version);
+                }
+                if (approval.hash && approval.hash !== description.sha256 && !options.approve)
+                    throw new CtlError('CTL_DESCRIPTION_CHANGED', 'Description hash changed; approval required.', `run: synopkgland ctl list --host ${this.host.name} --refresh --approve-installed`, 4);
+                approval.hash = description.sha256;
+                this.store.putCache(this.host, pkg.id, pkg.version, description);
+                return { description };
+            }
+            catch (error) {
+                const failure = errorData(error);
+                if (failure.code === 'CTL_DESCRIPTION_UNAVAILABLE')
+                    this.store.putFailure(this.host, pkg.id, pkg.version, failure);
+                return { error: { package: pkg.id, ...failure } };
+            }
+        });
+        this.host.lastUsed = new Date().toISOString();
+        this.store.save(this.host);
+        return { apps: results.flatMap(r => r.description ? [r.description] : []), diagnostics: results.flatMap(r => r.error ? [r.error] : []), cacheHits };
+    }
+    async execute(name, path, args, options = {}) {
+        const listing = await this.discover(options);
+        const app = selectApp(listing.apps, name);
+        const { id, operation } = selectOperation(app, path);
+        const params = operationInput(operation, args, options.stdin, `run: synopkgland ctl ${name} ${operation.cli.join(' ')} --host ${this.host.name} --help`);
+        const output = new SensitiveOutput(params, operation.paramsSchema);
+        try {
+            const plan = requestPlan(app, id, params);
+            if (operation.flow.type === 'upload')
+                localFile(params[operation.flow.fileParam]);
+            confirmOperation(operation, !!options.yes, !!options.dryRun, plan);
+            if (options.dryRun)
+                return { dryRun: true, request: plan };
+            const session = await this.store.session(this.host);
+            let appSession = session;
+            if (app.payload.transport.auth === 'dsm-app-session') {
+                const boot = await this.request(app.payload.transport.path, { method: 'identity.session', params: { bootstrap: true } }, session);
+                // The transport adapter adds only validated, path-scoped App cookies for this call.
+                if (boot?.success !== true)
+                    throw new CtlError('CTL_APP_SESSION', 'App session bootstrap failed; HTTPS is required.', `run: synopkgland ctl host show ${this.host.name}`, 5);
+                appSession = this.appCookieSession(session, boot);
+            }
+            try {
+                const invoke = async (method, input) => {
+                    if (!app.payload.bindings[method])
+                        throw new CtlError('CTL_METHOD_NOT_ALLOWED', 'Flow method is not allowlisted.', 'Refresh the API description.', 4);
+                    const response = await this.request(app.payload.transport.path, { method, params: input }, appSession);
+                    if (response?.success !== true) {
+                        const code = String(response?.error?.code ?? 'invalid_response');
+                        throw new CtlError(['admin_required', 'app_privilege_denied'].includes(code) ? 'CTL_PERMISSION_DENIED' : 'CTL_APP_ERROR', `App rejected operation (${code}).`, 'Check command permissions and App state.', ['admin_required', 'app_privilege_denied'].includes(code) ? 4 : 5);
+                    }
+                    return response.data;
+                };
+                const ca = this.host.ca ? readFileSync(this.host.ca, 'utf8') : undefined;
+                const result = await runFlow(operation.flow, params, invoke, { wait: options.wait, timeoutMs: options.timeoutMs,
+                    ndjson: (method, input) => transferRequest(appSession, app.payload.transport.path, method, input, { ca, timeoutMs: options.timeoutMs }),
+                    upload: (method, input, flow) => transferRequest(appSession, app.payload.transport.path, method, {}, { ca, timeoutMs: options.timeoutMs, file: { path: String(input[flow.fileParam]), parent: String(input[flow.parentParam]), name: String(input[flow.nameParam]) } }) });
+                if (operation.resultSchema && !ajv.validate(operation.resultSchema, result))
+                    throw new CtlError('CTL_RESPONSE_INVALID', 'Result does not match command schema.', 'Check the App version.', 5);
+                return output.clean(result, operation.resultSchema);
+            }
+            finally {
+                if (app.payload.transport.auth === 'dsm-app-session')
+                    await this.request(app.payload.transport.path, { method: 'identity.logout', params: {} }, appSession);
+            }
+        }
+        catch (error) {
+            throw output.error(error);
+        }
+    }
+    appCookieSession(session, body) { if (typeof body[APP_COOKIE] !== 'string' || !body[APP_COOKIE])
+        throw new CtlError('CTL_APP_SESSION', 'App bootstrap returned no scoped cookie.', 'Use HTTPS and a compatible App.', 5); return { ...session, cookie: session.cookie + '; ' + body[APP_COOKIE] }; }
+}

package/dist/ctl/store.d.ts

@@ -0,0 +1,51 @@
+import type { DsmSession } from './transport.js';
+export interface Approval {
+    version: string;
+    hash?: string;
+}
+export interface Host {
+    name: string;
+    origin: string;
+    username: string;
+    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;
+    list(): Host[];
+    get(name: string): Host;
+    save(host: Host): void;
+    add(host: Host, session: DsmSession): Promise<void>;
+    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/ctl/store.js

@@ -0,0 +1,93 @@
+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 './errors.js';
+import { publicDescriptor } from './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'); }
+    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) { 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 ctl 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;
+    } }
+    async session(host) { const 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 ctl 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 ctl 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)); return { removed: name, deleted: ['session', 'SynoToken', 'device token', 'App approvals', 'hash pins', 'list cache', 'host registration'] }; }
+}

package/dist/ctl/transfers.d.ts

@@ -0,0 +1,14 @@
+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;
+}): Promise<any>;

package/dist/ctl/transfers.js

@@ -0,0 +1,74 @@
+import { createReadStream, statSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import { CtlError } from './errors.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);
+    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 = (url.protocol === 'https:' ? https : http).request(url, { method: 'POST', headers, timeout: 30000, ...(options.ca ? { ca: options.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(), options.timeoutMs ?? 30000);
+        req.once('close', () => clearTimeout(wallTimer));
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => reject(new CtlError('CTL_NETWORK', 'Transfer interrupted; completion may be uncertain.', 'Check App state before retrying.', 6)));
+        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/ctl/transport.d.ts

@@ -0,0 +1,11 @@
+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, ca?: string): JsonRequest;