@synopackageland/sdk 0.9.5 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/sdk",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Frontend SDK for DSM packages built with synopkgland: headless client and Vue components",
   "license": "MIT",
   "homepage": "https://github.com/synopackageland/syno-pkg-land-sdk/tree/main/ts#readme",
@@ -53,7 +53,7 @@
   },
   "devDependencies": {
     "@lucide/vue": "1.48.0",
-    "@synopackageland/ui": "0.9.1",
+    "@synopackageland/ui": "0.9.2",
     "@types/node": "24.19.2",
     "@vitejs/plugin-vue": "6.0.9",
     "jsdom": "27.4.0",

package/spec/protocol/v1/README.md

@@ -40,9 +40,13 @@ the executor against the vectors here.
   `dsm_synotoken` and `remote_addr` (since 0.9.4), the browser's address
   (REMOTE_ADDR). DSM's Application Privileges are evaluated for that address;
   an op that checks them MUST be refused with `APP_DENIED` when a present
-  `auth` has no usable `remote_addr`. Requests without `auth` are checked as
-  coming from 127.0.0.1. A present `auth` is always treated as caller
-  authentication, never ignored, even when empty. Ops whose schema says
+  `auth` has no usable `remote_addr`. A grant records the `remote_addr` of the
+  `delegate.create` that made it (creating it again records the new one), and
+  an operation records the address of its `files.moveFromStaging` (since
+  0.9.6). A request without `auth` under a grant, and the operation's
+  background revalidation, are checked from that recorded address; work with no
+  recorded address is checked as coming from 127.0.0.1. A present `auth` is
+  always treated as caller authentication, never ignored, even when empty. Ops whose schema says
   `"auth": "required"` MUST be refused with `AUTH_DENIED` without a valid DSM
   session.
 - `params` MUST be an object valid against `schema/<op>.json`. A member that
@@ -70,9 +74,67 @@ the executor against the vectors here.
 ## Status
 
 `status` answers `version` (`"1"`), `ready`, `disabled`, `executor_digest`
-and `policy_digest`. The executor MUST NOT report the SDK version; the binary
+and `policy_digest`. With `auth` (since 0.9.6) it also answers `allowed`:
+whether DSM's Application Privileges let the caller use the App and File
+Station from `remote_addr`, the check `delegate.create` makes; an invalid
+session is `AUTH_DENIED`. A CGI sends the caller's `auth` so an App the
+executor would refuse is never shown as ready. The executor MUST NOT report the SDK version; the binary
 digest MUST change only when the executor source changes.
 
+## Application Portal
+
+Since 0.9.6. A policy MAY carry `"portal": {"application": "<display name>",
+"alias": "<default alias>"}` together with both `portal.register` and
+`portal.unregister`; a policy with only some of the three is invalid. The
+executor then registers the App's Application Portal entry the way DSM's
+web-config worker does, on every DSM version: an App whose `os_min_ver` is
+below 7.2 cannot declare that resource, since DSM 7.1 refuses it for unsigned
+packages.
+
+- Both ops take no params and require the session of an administrator whom
+  Application Privileges allow to use the App (`ADMIN_REQUIRED`,
+  `APP_DENIED`). The alias itself stays an administrator's
+  `SYNO.Core.AppPortal set`; the executor never writes it.
+- `portal.register` writes `/usr/syno/etc/www/app.d/<package>.mustache`, then
+  `<package>.json` (id `SYNO.SDS.<package>.Instance`), runs
+  `synow3tool --gen-app=<package>`, and requires `nginx -t` and the App in
+  `SYNO.Core.AppPortal list`. Registering again rewrites the same files.
+- `portal.unregister` removes both app.d files and
+  `/usr/syno/etc/packages/<package>/AppPortal.json`, disables and
+  unregisters every `{dsm,www,alias,.alias}.syno-app-portal.<package>.conf`
+  conf and `{server,.server}` site still enabled or still in DSM's registry,
+  and reloads nginx once `nginx -t` passes. A step with nothing to remove is
+  skipped, so the op MAY be repeated.
+- A failed change is `PORTAL_FAILED`. A failed register is undone the same
+  way. Until a later `portal.unregister` succeeds, `status` reports
+  `portal` `cleanup-required`.
+- The executor MUST remove the entry when it purges for an uninstall; DSM
+  does not.
+- `status` answers `portal` for such a policy: `registered` (the executor's
+  own files and DSM's generated conf), `unregistered`, or `cleanup-required`
+  (anything else, including a failed change).
+
+## Uninstall purge step
+
+Since 0.9.7. A policy MAY carry `"purge": "<name>"`, naming one of its `root`
+ops as the App's root step at uninstall; any other value makes the policy
+invalid. Approving that policy is the administrator's consent that the op
+runs as root at uninstall, with no session.
+
+- `root.run` MUST refuse that op with `POLICY_DENIED`: a session cannot start
+  the uninstall step early.
+- When the package account requests purge, the executor MUST run the op
+  before it removes Application Privileges rules, its portal entry and its
+  approval tasks, and only while the approval is live: the package ships the
+  approved executor and policy pins, and both approval tasks of that policy
+  stand with their exact scripts. Otherwise, and on an offline purge, it MUST
+  skip the op and log `purge root step skipped: not approved`.
+- The op gets the argument `delete-state` when the package account wrote
+  `delete-state` to `var/executor/uninstall` before its request (the
+  `executor/lifecycle purge --delete-state` helper does), and no argument
+  otherwise. It runs for at most 60 seconds; its exit status and output go to
+  the purge log, and a failure MUST NOT stop the rest of the purge.
+
 ## Grants
 
 - A time-limited grant (`job_id`, `ttl_seconds` ≤ 30 days) covers the listed
@@ -86,11 +148,12 @@ digest MUST change only when the executor source changes.
   Application Privileges, scope, directory identity and write permission
   against DSM. A failure the user or an administrator can undo MUST fail only
   that operation and MUST keep the grant: `PERMISSION_DENIED` (the ACL refuses
-  the write) and `not-found` (the granted folder is not at its path). Once the
-  cause is fixed, a new operation under the same grant succeeds. Any other
-  revalidation failure (`DELEGATION_DENIED`, `INELIGIBLE`, `APP_DENIED`,
-  `SCOPE_DENIED`, including a different folder at the granted path) MUST
-  revoke the grant; the user then chooses the destination again.
+  the write), `not-found` (the granted folder is not at its path) and, since
+  0.9.6, `APP_DENIED` (an Application Privileges rule refuses the account from
+  the checked address). Once the cause is fixed, a new operation under the same
+  grant succeeds. Any other revalidation failure (`DELEGATION_DENIED`,
+  `INELIGIBLE`, `SCOPE_DENIED`, including a different folder at the granted
+  path) MUST revoke the grant; the user then chooses the destination again.
 - `files.taskStatus` and `files.taskCancel` follow the task's op and MUST NOT
   be granted directly.
 - An administrator MAY turn the integration off with `delegate.disable`; then

package/spec/protocol/v1/errors.json

@@ -154,6 +154,14 @@
       "en": "The root operation exited with a non-zero status or failed to run.",
       "zh-TW": "root 操作以非零狀態結束，或無法執行。"
     },
+    {
+      "code": "PORTAL_FAILED",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 502,
+      "en": "DSM did not accept the Application Portal change; status portal says whether the entry needs another removal.",
+      "zh-TW": "DSM 未接受應用程式入口的變更；status 的 portal 說明是否需要再移除一次。"
+    },
     {
       "code": "NO_SPACE",
       "kind": "refusal",

package/spec/protocol/v1/schema/portal.register.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/synopackageland/syno-pkg-land-sdk/spec/protocol/v1/schema/portal.register.json",
+  "title": "portal.register",
+  "description": "Administrator: register the policy's Application Portal entry in DSM's app.d (DSM before 7.2 refuses the web-config resource of unsigned packages).",
+  "since": "0.9.6",
+  "auth": "required",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/spec/protocol/v1/schema/portal.unregister.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/synopackageland/syno-pkg-land-sdk/spec/protocol/v1/schema/portal.unregister.json",
+  "title": "portal.unregister",
+  "description": "Administrator: remove the App's Application Portal entry, its saved alias and every nginx conf DSM generated for it.",
+  "since": "0.9.6",
+  "auth": "required",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/spec/protocol/v1/vectors/files.jsonl

@@ -7,4 +7,5 @@
 {"name":"move-missing-size","request":{"v":1,"op":"files.moveFromStaging","params":{"delegation_id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","job_id":"export-20261009","staging":"exports/report.csv","name":"report.csv"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{"grants":[{"id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","username":"alice","key":"save","path":"/home/exports"}]},"expect":{"ok":false,"code":"INVALID_REQUEST"}}
 {"name":"operation-status-unknown","request":{"v":1,"op":"files.operationStatus","params":{"delegation_id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","job_id":"export-20261009"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{"grants":[{"id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","username":"alice","key":"save","path":"/home/exports"}]},"expect":{"ok":false,"code":"operation-not-found"}}
 {"name":"root-run-unpinned","request":{"v":1,"op":"root.run","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token"},"params":{"name":"whoami"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{},"expect":{"ok":false,"code":"POLICY_DENIED"}}
+{"name":"root-run-purge-step","request":{"v":1,"op":"root.run","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token"},"params":{"name":"purge"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{"purge":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},"purge":"purge"},"state":{},"expect":{"ok":false,"code":"POLICY_DENIED"}}
 {"name":"root-run-bad-name","request":{"v":1,"op":"root.run","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token"},"params":{"name":"../x"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{},"expect":{"ok":false,"code":"INVALID_REQUEST"}}

package/spec/protocol/v1/vectors/portal.jsonl

@@ -0,0 +1,8 @@
+{"name":"register","request":{"v":1,"op":"portal.register","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":true,"result":{"entry":"registered"}}}
+{"name":"unregister","request":{"v":1,"op":"portal.unregister","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":true,"result":{"entry":"unregistered"}}}
+{"name":"register-not-admin","request":{"v":1,"op":"portal.register","auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":false,"code":"ADMIN_REQUIRED"}}
+{"name":"unregister-not-admin","request":{"v":1,"op":"portal.unregister","auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":false,"code":"ADMIN_REQUIRED"}}
+{"name":"register-without-auth","request":{"v":1,"op":"portal.register","params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":false,"code":"AUTH_DENIED"}}
+{"name":"register-outside-policy","request":{"v":1,"op":"portal.register","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{},"expect":{"ok":false,"code":"POLICY_DENIED"}}
+{"name":"register-with-params","request":{"v":1,"op":"portal.register","auth":{"dsm_cookie":"admin","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{"alias":"x"}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":false,"code":"INVALID_REQUEST"}}
+{"name":"status-entry","request":{"v":1,"op":"status","params":{}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","portal.register","portal.unregister"],"portal":{"application":"Contract","alias":"contract"}},"state":{},"expect":{"ok":true,"result":{"portal":"unregistered"}}}

package/spec/protocol/v1/vectors/status.jsonl

@@ -1,2 +1,3 @@
 {"name":"ready","request":{"v":1,"op":"status","params":{}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{},"expect":{"ok":true,"result":{"version":"1","ready":true,"disabled":false,"executor_digest":"<any>","policy_digest":"<any>"}}}
 {"name":"disabled","request":{"v":1,"op":"status","params":{}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{"disabled":true},"expect":{"ok":true,"result":{"version":"1","ready":true,"disabled":true,"executor_digest":"<any>","policy_digest":"<any>"}}}
+{"name":"caller-allowed","request":{"v":1,"op":"status","params":{},"auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"}},"policy":{"v":1,"package":"contract","app":"app","scope":"home","operations":["status","delegate.create","delegate.list","delegate.revoke","files.list","files.write","files.moveFromStaging","files.operationStatus","files.cancelOperation","delegate.disable","delegate.enable","delegate.audit","root.run"],"destinations":["save"],"lifetime":"until-revoked","root":{}},"state":{},"expect":{"ok":true,"result":{"allowed":true}}}

package/dist/src/nas/i18n.d.ts

@@ -1,2 +0,0 @@
-/** Substitute the single display value in localized picker copy. */
-export declare function format(template: string, value: string | number): string;