@synopackageland/cli 0.3.8 → 0.3.10

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,4 +1,7 @@
+import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
 import type { InstalledPackageState } from "./catalog-install.js";
+import type { PortInfoEntry } from "./port-info.js";
+import type { DsmPortProfileInventory } from "./dsm-port-profile.js";
 export type AttestationKind = "local" | "app-package" | "none";
 export type PackageRoute = "package-only" | "broker-installer" | "unknown";
 export type OidcOriginKind = "public-ca" | "quickconnect" | "lan-ip" | "self-signed" | "private-ca" | "http";
@@ -79,6 +82,16 @@ 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>;
+    /** Read SYNO.Core.Service.PortInfo/load using an administrator session. */
+    listPortInfo?(): Promise<PortInfoEntry[] | 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>;
@@ -94,6 +107,12 @@ export interface NasHost {
         isPackageOnly?: boolean;
         [key: string]: unknown;
     } | undefined>;
+    /**
+     * Read DSM PortInfo plus the administrator-visible installed package list.
+     * This path does not require SynoPkgLandService; undefined means the host
+     * could not answer and must be treated as unknown by diagnostics.
+     */
+    getDsmPortProfileInventory?(): Promise<DsmPortProfileInventory | undefined>;
     /** Read the optional administrator OIDC compatibility settings endpoint. */
     getOidcCompatSettings?(): Promise<HostOidcCompatSettings | undefined>;
     smokeRequireLogin(input: {

package/package.json

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