@synopackageland/sdk 0.10.11 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/sdk",
-  "version": "0.10.11",
+  "version": "0.11.0",
   "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",
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@lucide/vue": "^1.48.0",
-    "@synopackageland/ui": "^0.9.5",
+    "@synopackageland/ui": "^0.9.10",
     "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
@@ -57,7 +57,7 @@
   },
   "devDependencies": {
     "@lucide/vue": "1.48.0",
-    "@synopackageland/ui": "0.9.9",
+    "@synopackageland/ui": "0.9.10",
     "@types/node": "24.19.2",
     "@vitejs/plugin-vue": "6.0.9",
     "jsdom": "27.4.0",

package/spec/protocol/v1/README.md

@@ -447,3 +447,30 @@ administrator). Their `dsm_cookie` is the user name and `dsm_synotoken` is
 
 New ops and members are added with a `since` of the SDK release. The protocol
 `v` changes only for an incompatible envelope change.
+
+## JSON WebAPI grants (since 0.11.0)
+
+`webapi.call` MUST execute only an exact API/method/version in the grant's named
+`webapi` policy profile, with `runner` fixed to its owner. A profile has `purpose`
+and `apis` (API -> method -> integer version array). It is part of the approved
+policy digest. Grants MUST additionally pin their profile and revalidate the
+account, UID, Application Privileges and original-address rules on every call.
+`delegate.create` with only `webapi.call` uses `scope` as the profile name and
+MUST omit file path/destination fields. It accepts job-bound TTL up to 30 days
+or `lifetime:"until-revoked"`; all other grant rules remain unchanged. Mixing
+file and WebAPI operations MUST be refused. Revoke and the integration disable
+switch MUST fence WebAPI admission and drain admitted calls before acknowledging.
+
+Core, Auth, API/Entry dispatch, FileStation and administrative namespaces/methods
+MUST be refused even if declared (executor/README.md lists the permanent denylist).
+Routing, runner, authentication and identity arguments MUST be refused. The
+encoded params object MUST be at most 32 KiB, the JSON DSM envelope at most
+48 KiB, and the call deadline at most 10 seconds including account revalidation.
+Duplicate JSON keys MUST be refused. The wire frame remains at most 64 KiB.
+Every admitted call MUST be audited without recording params/results.
+
+Protocol success returns the full DSM success/error envelope. No automatic
+mutation retries are permitted. A dispatched call whose execution/reply/audit
+cannot be confirmed MUST answer `WEBAPI_UNCERTAIN` (nonretryable); client
+transport failure MAY also hide a completed operation. Binary/streaming replies
+MUST be refused. These bounds and semantics also apply to until-revoked grants.

package/spec/protocol/v1/errors.json

@@ -513,6 +513,14 @@
       "httpStatus": 502,
       "en": "The executor reply is not a valid v1 response.",
       "zh-TW": "executor 的回應不是有效的 v1 回應。"
+    },
+    {
+      "code": "WEBAPI_UNCERTAIN",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 502,
+      "en": "The WebAPI outcome is unknown: execution, reply validation or audit completion failed. Do not automatically retry a mutation.",
+      "zh-TW": "WebAPI 結果不確定：執行、回覆驗證或稽核完成失敗。請勿自動重試寫入操作。"
     }
   ]
 }

package/spec/protocol/v1/schema/delegate.create.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/synopackageland/syno-pkg-land-sdk/spec/protocol/v1/schema/delegate.create.json",
   "title": "delegate.create",
-  "description": "Create a time-limited grant (job_id, ttl_seconds) or an until-revoked destination grant (destination, lifetime).",
+  "description": "Create a time-limited grant (job_id, ttl_seconds) or an until-revoked destination grant (destination, lifetime). Since 0.11.0: ops [webapi.call], scope is a named WebAPI profile, omit path/destination; job_id + ttl_seconds or lifetime until-revoked.",
   "since": "0.9.0",
   "auth": "required",
   "type": "object",
@@ -16,7 +16,7 @@
       "minItems": 1,
       "items": {
         "type": "string",
-        "pattern": "^files\\."
+        "pattern": "^(files\\.|webapi\\.call$)"
       }
     },
     "scope": {
@@ -43,7 +43,6 @@
   "additionalProperties": false,
   "required": [
     "ops",
-    "scope",
-    "path"
+    "scope"
   ]
 }

package/spec/protocol/v1/schema/webapi.call.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/synopackageland/syno-pkg-land-sdk/spec/protocol/v1/schema/webapi.call.json",
+  "title": "webapi.call",
+  "description": "Call an exact approved JSON WebAPI as the profile grant owner. Never retried; the result is the full DSM success/error envelope.",
+  "since": "0.11.0",
+  "auth": "optional",
+  "type": "object",
+  "properties": {
+    "delegation_id": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "job_id": {
+      "type": "string"
+    },
+    "api": {
+      "type": "string"
+    },
+    "method": {
+      "type": "string"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535
+    },
+    "params": {
+      "type": "object",
+      "description": "JSON API arguments, at most 32768 encoded bytes; authentication, runner and dispatch keys are forbidden."
+    }
+  },
+  "required": [
+    "delegation_id",
+    "api",
+    "method",
+    "version",
+    "params"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,3 @@
+{"name":"timed","request":{"v":1,"op":"delegate.create","auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{"ops":["webapi.call"],"scope":"calendar","job_id":"j1","ttl_seconds":60}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","delegate.create","delegate.list","delegate.revoke","webapi.call"],"webapi":{"calendar":{"purpose":"Create calendar reminders","apis":{"SYNO.Cal.Event":{"list":[6],"create":[6],"delete":[6]}}}}},"state":{},"expect":{"ok":true,"result":{"delegation_id":"<any>","scope":"calendar"}}}
+{"name":"until-revoked","request":{"v":1,"op":"delegate.create","auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{"ops":["webapi.call"],"scope":"calendar","lifetime":"until-revoked"}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","delegate.create","delegate.list","delegate.revoke","webapi.call"],"webapi":{"calendar":{"purpose":"Create calendar reminders","apis":{"SYNO.Cal.Event":{"list":[6],"create":[6],"delete":[6]}}}}},"state":{},"expect":{"ok":true,"result":{"delegation_id":"<any>","scope":"calendar"}}}
+{"name":"reject-files-mix","request":{"v":1,"op":"delegate.create","auth":{"dsm_cookie":"alice","dsm_synotoken":"contract-token","remote_addr":"192.0.2.1"},"params":{"ops":["webapi.call","files.list"],"scope":"calendar","job_id":"j1","ttl_seconds":60}},"policy":{"v":1,"package":"contract","app":"app","operations":["status","delegate.create","delegate.list","delegate.revoke","webapi.call"],"webapi":{"calendar":{"purpose":"Create calendar reminders","apis":{"SYNO.Cal.Event":{"list":[6],"create":[6],"delete":[6]}}}}},"state":{},"expect":{"ok":false,"code":"INVALID_REQUEST"}}