@synopackageland/cli 0.3.8 → 0.3.9

package/dist/cli.js

@@ -274,6 +274,9 @@ export async function runCli(argv) {
                 console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
                 process.exit(1);
             }
+            for (const note of result.notes ?? []) {
+                console.warn(`[注意] ${note}`);
+            }
             console.log(`已部署 ${result.packageId}`);
             if (result.openUrl) {
                 console.log(`Open URL：${result.openUrl}`);

package/dist/deploy/deploy.d.ts

@@ -24,5 +24,7 @@ export interface DeployProjectResult {
     spkPath?: string;
     openUrl?: string;
     catalogVersion?: string;
+    /** Non-blocking pre-flight remarks, e.g. a read-only Shared Folder grant. */
+    notes?: string[];
 }
 export declare function deployProject(options: DeployProjectOptions): Promise<DeployProjectResult>;

package/dist/deploy/deploy.js

@@ -9,6 +9,7 @@ import { resolveDeployIdentity, PACKAGE_IDENTITY_MAX_LENGTH } from "./identity.j
 import { resolveDeploySpkVersion } from "./spk-version.js";
 import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
 import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-values.js";
+import { runSharePermissionPreflight } from "./share-permission-preflight.js";
 import { homesParameterNames, resolveHomesExtraValues } from "./homes-values.js";
 import { resolveInstallParameterExtraValues } from "./param-values.js";
 import { CURATED_BUILD_OFFSET } from "@synopackageland/package-source/index-manifest";
@@ -124,6 +125,24 @@ export async function deployProject(options) {
     if (!runAsResolved.ok) {
         return { ok: false, code: runAsResolved.code, message: runAsResolved.message };
     }
+    // A42 pre-flight: preinst runs as the package user and can never read ACL, so
+    // the only place that can catch "selected user cannot reach selected Share" is
+    // here, where we still hold an administrator session. Refuses before install.
+    const sharePermission = await runSharePermissionPreflight({
+        shares: Object.fromEntries(sharedFolderParameterNames(contract)
+            .map((key) => [key, (options.shareValues ?? {})[key] ?? ""])
+            .filter(([, value]) => value.trim() !== "")),
+        runAsUsers: runAsResolved.extraValues,
+        listSharePermissions: options.host.listSharePermissions
+            ? (name) => options.host.listSharePermissions(name)
+            : undefined,
+        listUserGroups: options.host.listUserGroups
+            ? (name) => options.host.listUserGroups(name)
+            : undefined,
+    });
+    if (!sharePermission.ok) {
+        return { ok: false, code: sharePermission.code, message: sharePermission.message };
+    }
     const extraValues = {
         ...paramResolved.extraValues,
         ...homesResolved.extraValues,
@@ -273,5 +292,6 @@ export async function deployProject(options) {
         spkPath: build.outputPath,
         openUrl: info.openUrl ?? appOriginFromContract(options.host.dsmOrigin, contract),
         catalogVersion,
+        notes: sharePermission.notes.length > 0 ? sharePermission.notes : undefined,
     };
 }

package/dist/deploy/share-permission-preflight.d.ts

@@ -0,0 +1,37 @@
+import { type SharePermissionRow } from "../host/share-permission.js";
+export declare const SHARE_RUN_AS_NO_ACCESS = "SHARE_RUN_AS_NO_ACCESS";
+export interface SharePermissionListing {
+    users: SharePermissionRow[];
+    groups: SharePermissionRow[];
+}
+export interface SharePermissionPreflightInput {
+    /** Logical Share names to check, keyed by the contract parameter name. */
+    shares: Record<string, string>;
+    /** Selected DSM user logical names, keyed by the contract parameter name. */
+    runAsUsers: Record<string, string>;
+    listSharePermissions?: (shareName: string) => Promise<SharePermissionListing | undefined>;
+    listUserGroups?: (userName: string) => Promise<string[] | undefined>;
+}
+export type SharePermissionPreflightResult = {
+    ok: true;
+    notes: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Ask the NAS, with the administrator session `deploy` already holds, whether
+ * every selected Run-as user can reach every selected Shared Folder.
+ *
+ * Deliberate boundaries:
+ * - This is a pre-flight, not enforcement. Package Center installs do not come
+ *   through here, and share permission can change after the install.
+ * - "Cannot tell" never becomes a refusal: a host without the capability, an
+ *   API that failed, an empty listing, or an advanced/Windows ACL (`is_custom`,
+ *   readable only by root-only synoacltool) all pass through.
+ * - `posix_all_shares` is out of scope on purpose. It means "mount every Share,
+ *   read-only" -- gating it on permission would refuse almost every install,
+ *   and the read-only bind already limits the damage.
+ */
+export declare function runSharePermissionPreflight(input: SharePermissionPreflightInput): Promise<SharePermissionPreflightResult>;

package/dist/deploy/share-permission-preflight.js

@@ -0,0 +1,81 @@
+import { evaluateShareAccess } from "../host/share-permission.js";
+export const SHARE_RUN_AS_NO_ACCESS = "SHARE_RUN_AS_NO_ACCESS";
+/**
+ * Ask the NAS, with the administrator session `deploy` already holds, whether
+ * every selected Run-as user can reach every selected Shared Folder.
+ *
+ * Deliberate boundaries:
+ * - This is a pre-flight, not enforcement. Package Center installs do not come
+ *   through here, and share permission can change after the install.
+ * - "Cannot tell" never becomes a refusal: a host without the capability, an
+ *   API that failed, an empty listing, or an advanced/Windows ACL (`is_custom`,
+ *   readable only by root-only synoacltool) all pass through.
+ * - `posix_all_shares` is out of scope on purpose. It means "mount every Share,
+ *   read-only" -- gating it on permission would refuse almost every install,
+ *   and the read-only bind already limits the damage.
+ */
+export async function runSharePermissionPreflight(input) {
+    const shareEntries = Object.entries(input.shares).filter(([, name]) => name.trim() !== "");
+    const userEntries = Object.entries(input.runAsUsers).filter(([, name]) => name.trim() !== "");
+    if (shareEntries.length === 0 || userEntries.length === 0) {
+        return { ok: true, notes: [] };
+    }
+    if (!input.listSharePermissions || !input.listUserGroups) {
+        return { ok: true, notes: [] };
+    }
+    const notes = [];
+    const groupCache = new Map();
+    const listingCache = new Map();
+    for (const [shareKey, shareName] of shareEntries) {
+        let listing = listingCache.get(shareName);
+        if (!listingCache.has(shareName)) {
+            try {
+                listing = await input.listSharePermissions(shareName);
+            }
+            catch {
+                listing = undefined;
+            }
+            listingCache.set(shareName, listing);
+        }
+        if (!listing) {
+            continue;
+        }
+        for (const [userKey, userName] of userEntries) {
+            let groups = groupCache.get(userName);
+            if (!groupCache.has(userName)) {
+                try {
+                    groups = await input.listUserGroups(userName);
+                }
+                catch {
+                    groups = undefined;
+                }
+                groupCache.set(userName, groups);
+            }
+            if (!groups) {
+                continue;
+            }
+            const verdict = evaluateShareAccess({
+                userName,
+                userGroups: groups,
+                userRows: listing.users,
+                groupRows: listing.groups,
+            });
+            if (verdict.access === "denied" || verdict.access === "none") {
+                const cause = verdict.access === "denied"
+                    ? `被「${verdict.deniedBy}」明確拒絕`
+                    : "在使用者本身與其所屬群組都沒有任何授權";
+                return {
+                    ok: false,
+                    code: SHARE_RUN_AS_NO_ACCESS,
+                    message: `Container Run-as「${userKey}=${userName}」對 Shared Folder「${shareKey}=${shareName}」${cause}。` +
+                        "容器會以該使用者的身分掛載這個 Share，安裝雖然會成功，但讀寫會在 runtime 拿到 Permission denied。" +
+                        `請先在 DSM 控制台把 ${shareName} 的權限給 ${userName}，或改選另一個使用者／Share。`,
+                };
+            }
+            if (verdict.access === "read") {
+                notes.push(`Run-as「${userName}」對 Shared Folder「${shareName}」只有唯讀權限（來源 ${verdict.grantedBy}）。若 App 需要寫入會在 runtime 失敗。`);
+            }
+        }
+    }
+    return { ok: true, notes };
+}

package/dist/error-registry.js

@@ -499,6 +499,11 @@ export const ERROR_REGISTRY = {
         description: "dsm_user 參數必須提供 DSM 使用者邏輯名稱，禁止使用數字 UID。",
         suggestion: "請在 --run-as 指定 DSM 使用者帳號名稱（例如 --run-as RUN_AS=alice）。",
     },
+    SHARE_RUN_AS_NO_ACCESS: {
+        code: "SHARE_RUN_AS_NO_ACCESS",
+        description: "deploy 的安裝前檢查發現選定的 Container Run-as 使用者對選定的 Shared Folder 沒有權限（或被明確拒絕）。容器會以該使用者掛載該 Share，安裝會成功但 runtime 讀寫會拿到 Permission denied。",
+        suggestion: "請在 DSM 控制台把該 Shared Folder 的權限授予該使用者（或其群組），或改選別的使用者／Share，再重新部署。此檢查只在 deploy 進行；Package Center 安裝精靈不經過這裡，ACL 仍是管理員的前提責任。",
+    },
     CURATED_DEPLOY_REFUSED: {
         code: "CURATED_DEPLOY_REFUSED",
         description: "目標 NAS 已持有 Curated App Package Attestation，禁止隨意覆蓋部署。",

package/dist/host/dsm-client.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { IDENTITY_CGI_PATH } from "./broker-paths.js";
 import { packageSourceOrigin } from "../deploy/catalog-publish.js";
 import { listShareNamesWithSynoagentcli, lookupSharePathWithSynoagentcli } from "./share-lookup.js";
+import { createSynoagentcliApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
 import { dsmFetch } from "./dsm-http.js";
 import { installPackageFromCatalog, installPackageFromLocalSpk, uninstallPackageFromDsm, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
@@ -234,6 +235,12 @@ function createDsmNasHost(credentials, profileName) {
         async listShareNames() {
             return listShareNamesWithSynoagentcli(profileName);
         },
+        async listSharePermissions(logicalName) {
+            return fetchSharePermissions(logicalName, createSynoagentcliApiCall(profileName));
+        },
+        async listUserGroups(userName) {
+            return fetchUserGroups(userName, createSynoagentcliApiCall(profileName));
+        },
         async resolveHomesPath() {
             try {
                 const result = synoagentcli(["dsm", "control-panel", "user-group", "advanced", "get", "--section", "home"], profileName);

package/dist/host/fake-nas.d.ts

@@ -1,4 +1,8 @@
+import type { SharePermissionRow } from "./share-permission.js";
 import type { AttestationKind, HostInstallRecord, HostOidcCompatSettings, NasHost, PackageRoute } from "./types.js";
+export type SharePermissionRowInput = {
+    name: string;
+} & Partial<Omit<SharePermissionRow, "name">>;
 export interface FakeNasHostOptions {
     curated?: string[];
     dsmOrigin?: string;
@@ -6,6 +10,17 @@ export interface FakeNasHostOptions {
     installationId?: string;
     shareNames?: string[];
     shares?: Record<string, string>;
+    /**
+     * SYNO.Core.Share.Permission rows per Share, as partials -- every flag
+     * defaults to false, matching a row DSM grants nothing on. Omit the whole
+     * option to model a host that cannot answer the permission question.
+     */
+    sharePermissions?: Record<string, {
+        users: SharePermissionRowInput[];
+        groups: SharePermissionRowInput[];
+    }>;
+    /** Group membership per DSM user, for share-permission resolution. */
+    userGroups?: Record<string, string[]>;
     installedEnv?: Record<string, Record<string, string>>;
     diagnostics?: {
         dsmResidue?: import("./types.js").DsmResidueInventory;

package/dist/host/fake-nas.js

@@ -1,4 +1,14 @@
 import { webStationAlias } from "../contract/web-launch.js";
+function sharePermissionRow(input) {
+    return {
+        is_admin: false,
+        is_writable: false,
+        is_readonly: false,
+        is_deny: false,
+        is_custom: false,
+        ...input,
+    };
+}
 export function createFakeNasHost(options = {}) {
     const dsmOrigin = options.dsmOrigin ?? "http://nas.example:5000";
     const installationId = options.installationId ?? "fake-installation";
@@ -32,6 +42,27 @@ export function createFakeNasHost(options = {}) {
         async listShareNames() {
             return [...shareNames];
         },
+        ...(options.sharePermissions
+            ? {
+                async listSharePermissions(logicalName) {
+                    const listing = options.sharePermissions?.[logicalName];
+                    if (!listing) {
+                        return undefined;
+                    }
+                    return {
+                        users: listing.users.map(sharePermissionRow),
+                        groups: listing.groups.map(sharePermissionRow),
+                    };
+                },
+            }
+            : {}),
+        ...(options.userGroups
+            ? {
+                async listUserGroups(userName) {
+                    return options.userGroups?.[userName];
+                },
+            }
+            : {}),
         async resolveHomesPath() {
             return options.homesPath;
         },

package/dist/host/share-permission-lookup.d.ts

@@ -0,0 +1,23 @@
+import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
+import type { SharePermissionRow } from "./share-permission.js";
+/**
+ * Reads DSM share permission with the administrator session `deploy` holds.
+ *
+ * Every parser returns `undefined` rather than an empty result when the answer
+ * is missing or malformed: downstream, `undefined` means "cannot tell" and lets
+ * the install proceed, while an empty list would read as a real denial and
+ * refuse the install on a transport error.
+ *
+ * The APIs used were confirmed present on DSM 7.4 (vt-nas):
+ * `SYNO.Core.Share.Permission`, `SYNO.Core.Group`, `SYNO.Core.Group.Member`.
+ * `SYNO.Core.User.Group` also exists on the NAS but has no generated
+ * synoagentcli operation, which is why membership is derived group-by-group.
+ */
+export type DsmApiCall = (operationId: string, params: Record<string, string>) => Promise<unknown>;
+export declare function parseSharePermissionRows(payload: unknown): SharePermissionRow[] | undefined;
+export declare function parseGroupNames(payload: unknown): string[] | undefined;
+export declare function parseGroupMemberNames(payload: unknown): string[] | undefined;
+export declare function fetchSharePermissions(shareName: string, call: DsmApiCall): Promise<SharePermissionListing | undefined>;
+export declare function fetchUserGroups(userName: string, call: DsmApiCall): Promise<string[] | undefined>;
+/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
+export declare function createSynoagentcliApiCall(profileName?: string): DsmApiCall;

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

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+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";
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Unwrap the synoagentcli envelope down to the DSM `data` object. */
+function dsmData(payload) {
+    const outer = asRecord(payload);
+    if (!outer || outer.success === false) {
+        return undefined;
+    }
+    const inner = asRecord(outer.data);
+    const response = asRecord(inner?.response);
+    return asRecord(response?.data) ?? asRecord(inner?.data);
+}
+function flag(record, key) {
+    return record[key] === true;
+}
+export function parseSharePermissionRows(payload) {
+    const data = dsmData(payload);
+    const items = data?.items;
+    if (!Array.isArray(items)) {
+        return undefined;
+    }
+    const rows = [];
+    for (const item of items) {
+        const record = asRecord(item);
+        const name = record?.name;
+        if (typeof name !== "string" || name === "") {
+            continue;
+        }
+        rows.push({
+            name,
+            is_admin: flag(record, "is_admin"),
+            is_writable: flag(record, "is_writable"),
+            is_readonly: flag(record, "is_readonly"),
+            is_deny: flag(record, "is_deny"),
+            is_custom: flag(record, "is_custom"),
+        });
+    }
+    return rows.length > 0 ? rows : undefined;
+}
+function parseNames(payload, key) {
+    const data = dsmData(payload);
+    const list = data?.[key];
+    if (!Array.isArray(list)) {
+        return undefined;
+    }
+    const names = [];
+    for (const item of list) {
+        const name = asRecord(item)?.name;
+        if (typeof name === "string" && name !== "") {
+            names.push(name);
+        }
+    }
+    return names;
+}
+export function parseGroupNames(payload) {
+    const names = parseNames(payload, "groups");
+    return names && names.length > 0 ? names : undefined;
+}
+export function parseGroupMemberNames(payload) {
+    return parseNames(payload, "users");
+}
+export async function fetchSharePermissions(shareName, call) {
+    const read = async (userGroupType) => {
+        try {
+            return parseSharePermissionRows(await call(SHARE_PERMISSION_OPERATION, {
+                name: shareName,
+                user_group_type: userGroupType,
+                offset: "0",
+                limit: "-1",
+            }));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const users = await read("local_user");
+    const groups = await read("local_group");
+    // A half-read listing could hide the very row that grants or denies access.
+    if (!users || !groups) {
+        return undefined;
+    }
+    return { users, groups };
+}
+export async function fetchUserGroups(userName, call) {
+    let groupNames;
+    try {
+        groupNames = parseGroupNames(await call(GROUP_LIST_OPERATION, { offset: "0", limit: "-1" }));
+    }
+    catch {
+        return undefined;
+    }
+    if (!groupNames) {
+        return undefined;
+    }
+    const memberships = [];
+    for (const groupName of groupNames) {
+        let members;
+        try {
+            members = parseGroupMemberNames(await call(GROUP_MEMBER_OPERATION, { group: groupName, offset: "0", limit: "-1" }));
+        }
+        catch {
+            return undefined;
+        }
+        // One unreadable group could be the one that grants access, so a partial
+        // membership set must never be used to refuse an install.
+        if (!members) {
+            return undefined;
+        }
+        if (members.includes(userName)) {
+            memberships.push(groupName);
+        }
+    }
+    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;
+        }
+    };
+}

package/dist/host/share-permission.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Folder permission pre-flight for the dynamic package-only route.
+ *
+ * Why this lives here and not in the SPK's preinst: preinst runs as the
+ * low-privilege package user, which cannot read ACL at all -- `synoacltool -get`
+ * answers `Access deny` and there is no CAP_SETUID to try the access as the
+ * selected user. The two places that *do* hold an administrator session are the
+ * install wizard and CLI `deploy`, so the check belongs to them. That makes it a
+ * pre-flight guard, not an enforcement gate: `deploy` can still be handed
+ * extra_values directly, and share permission can change after install.
+ *
+ * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
+ * before changing the predicate: on vt-nas, `newadmin` has is_writable=false on
+ * its own row for `pkgland-p0b` and still writes there, because the
+ * `administrators` group row carries the grant. A user-row-only check rejects
+ * the only configuration with live proof behind it.
+ */
+export interface SharePermissionRow {
+    name: string;
+    is_admin: boolean;
+    is_writable: boolean;
+    is_readonly: boolean;
+    is_deny: boolean;
+    is_custom: boolean;
+}
+export type ShareAccess = "write" | "read" | "none" | "denied" | "unknown";
+export interface ShareAccessVerdict {
+    access: ShareAccess;
+    /** Which row granted access, as `user:<name>` or `group:<name>`. */
+    grantedBy?: string;
+    /** Which row denied access, as `user:<name>` or `group:<name>`. */
+    deniedBy?: string;
+    /** Why an `unknown` verdict could not be decided. */
+    reason?: "custom-acl" | "no-rows";
+}
+export interface ShareAccessInput {
+    userName: string;
+    /** Group names the user belongs to. Matched exactly -- no case folding. */
+    userGroups: readonly string[];
+    userRows: readonly SharePermissionRow[];
+    groupRows: readonly SharePermissionRow[];
+}
+export declare function evaluateShareAccess(input: ShareAccessInput): ShareAccessVerdict;

package/dist/host/share-permission.js

@@ -0,0 +1,59 @@
+/**
+ * Shared Folder permission pre-flight for the dynamic package-only route.
+ *
+ * Why this lives here and not in the SPK's preinst: preinst runs as the
+ * low-privilege package user, which cannot read ACL at all -- `synoacltool -get`
+ * answers `Access deny` and there is no CAP_SETUID to try the access as the
+ * selected user. The two places that *do* hold an administrator session are the
+ * install wizard and CLI `deploy`, so the check belongs to them. That makes it a
+ * pre-flight guard, not an enforcement gate: `deploy` can still be handed
+ * extra_values directly, and share permission can change after install.
+ *
+ * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
+ * before changing the predicate: on vt-nas, `newadmin` has is_writable=false on
+ * its own row for `pkgland-p0b` and still writes there, because the
+ * `administrators` group row carries the grant. A user-row-only check rejects
+ * the only configuration with live proof behind it.
+ */
+function relevantRows(input) {
+    const groups = new Set(input.userGroups);
+    const candidates = [];
+    for (const row of input.userRows) {
+        if (row.name === input.userName) {
+            candidates.push({ row, label: `user:${row.name}` });
+        }
+    }
+    for (const row of input.groupRows) {
+        if (groups.has(row.name)) {
+            candidates.push({ row, label: `group:${row.name}` });
+        }
+    }
+    return candidates;
+}
+export function evaluateShareAccess(input) {
+    // An empty listing means the API answer was missing or truncated. Reading
+    // that as a denial would block installs on a transport error.
+    if (input.userRows.length === 0 && input.groupRows.length === 0) {
+        return { access: "unknown", reason: "no-rows" };
+    }
+    const candidates = relevantRows(input);
+    // Advanced/Windows ACL overrides share permission and only root-only
+    // synoacltool can read it, so any custom row in the deciding set makes the
+    // whole verdict inconclusive -- in both directions.
+    if (candidates.some(({ row }) => row.is_custom)) {
+        return { access: "unknown", reason: "custom-acl" };
+    }
+    const denied = candidates.find(({ row }) => row.is_deny);
+    if (denied) {
+        return { access: "denied", deniedBy: denied.label };
+    }
+    const writable = candidates.find(({ row }) => row.is_admin || row.is_writable);
+    if (writable) {
+        return { access: "write", grantedBy: writable.label };
+    }
+    const readable = candidates.find(({ row }) => row.is_readonly);
+    if (readable) {
+        return { access: "read", grantedBy: readable.label };
+    }
+    return { access: "none" };
+}

package/dist/host/types.d.ts

@@ -1,3 +1,4 @@
+import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
 import type { InstalledPackageState } from "./catalog-install.js";
 export type AttestationKind = "local" | "app-package" | "none";
 export type PackageRoute = "package-only" | "broker-installer" | "unknown";
@@ -79,6 +80,14 @@ export interface NasHost {
     /** List the current logical Shared Folder names using an administrator session. */
     listShareNames?(): Promise<string[]>;
     resolveSharePath?(logicalName: string): Promise<string | undefined>;
+    /**
+     * Read SYNO.Core.Share.Permission for one Share using an administrator
+     * session. Returns undefined when the host cannot answer -- callers must
+     * treat that as "cannot tell", never as a denial.
+     */
+    listSharePermissions?(logicalName: string): Promise<SharePermissionListing | undefined>;
+    /** Group names a DSM user belongs to, for resolving share permission. */
+    listUserGroups?(userName: string): Promise<string[] | undefined>;
     /** Resolve the NAS-specific user-home root when DSM User Home is enabled. */
     resolveHomesPath?(): Promise<string | undefined>;
     getInstalledProjectEnv?(packageIdentity: string): Promise<Record<string, string> | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {