@colixsystems/widget-sdk 0.88.0 → 0.89.0

package/README.md

@@ -61,7 +61,33 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.88.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.89.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.89.0 (contract unchanged)
+
+**New linter rule `write-not-gated-on-user` — a widget that writes must decide what a signed-OUT visitor sees (sc-4985).**
+
+- **`write-not-gated-on-user` (severity `warning`, non-blocking).** A widget that
+  writes with `useDatastoreMutation` but carries no identity guard is flagged. A
+  write needs a signed-in app user, so an anonymous visitor handed a live
+  "Save" / "Book" / "Delete" button can only ever tap it and fail. Author fix:
+  read `useUser()` and branch **before** rendering the control — when `!user.id`
+  keep the affordance as a visibly-inactive signpost with a translated "sign in"
+  line and **no press handler** (a widget cannot open the login surface; that is
+  a built-in Button's `sign-in` action, wired by the page author), and when the
+  user is signed in but not permitted, leave the control out entirely.
+- **Reading `useUser().id` as a VALUE does not satisfy it.** The canonical
+  USER-column write pattern (`create({ [memberField]: user.id })`) calls
+  `useUser()` without ever branching on it — the case most easily mistaken for a
+  gate — so the rule requires an operator after `.id` (a negation, a ternary,
+  `&&`, a comparison) or a `groupIds` / `roles` check.
+- **Why a warning.** It is conservative on purpose: an unrelated `.id`
+  comparison elsewhere in the source silences it. A rule that occasionally stays
+  quiet is far cheaper than one that cries wolf on correct code, and gating is an
+  affordance decision — the server remains the only authority, so the `catch`
+  stays either way.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
 
 ### What's new in 0.88.0 (contract 1.62.0)
 

package/dist/linter.cjs

@@ -789,6 +789,49 @@ const CURRENCY_LABEL_RES = [
   /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
 ];
 
+// sc-4985 — soft warning: a widget that writes must decide what a signed-OUT
+// visitor sees. A write needs a signed-in app user, so an anonymous visitor
+// handed a live "Save" / "Book" / "Delete" button can only tap it and fail —
+// the failure the gate exists to spare them. Satisfied by any identity guard:
+// a negated or compared `.id`, or a `groupIds` / `roles` check. Reading
+// `useUser().id` purely as a VALUE (the USER-column write pattern) is NOT a
+// guard, which is why an operator has to follow it.
+//
+// Conservative on purpose: an unrelated `.id` comparison elsewhere in the
+// source silences the rule. A warning that occasionally stays quiet is far
+// cheaper than one that cries wolf on correct code.
+const _IDENTITY_GUARD_RES = [
+  // `!user.id` / `!user?.id`
+  /![\s(]*\w+\??\.id\b/,
+  // `user.id ?` / `&&` / `||` / `===` / `!==` / `==` / `!=`
+  /\w+\??\.id\s*(\?[^.]|&&|\|\||===|!==|==|!=)/,
+  // any group / role check the brief asked for
+  /\bgroupIds\b/,
+  /\broles\b/,
+];
+
+function _writeGatedOnUserRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "write-not-gated-on-user",
+      severity: "warning",
+      // Kept under ~210 chars: a finding is truncated at 300 downstream, and
+      // the fix instruction is the half worth keeping.
+      label:
+        `writes with useDatastoreMutation() but never checks who is signed ` +
+        `in - read useUser(), and when !user.id render the action inactive ` +
+        `with a "sign in" line instead of a live button that can only fail.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _hardcodedCurrencyLabelRules(source) {
   const code = _stripNonCode(source, { keepStrings: true });
   if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
@@ -1039,6 +1082,7 @@ function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/dist/linter.js

@@ -921,6 +921,49 @@ const CURRENCY_LABEL_RES = [
   /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
 ];
 
+// sc-4985 — soft warning: a widget that writes must decide what a signed-OUT
+// visitor sees. A write needs a signed-in app user, so an anonymous visitor
+// handed a live "Save" / "Book" / "Delete" button can only tap it and fail —
+// the failure the gate exists to spare them. Satisfied by any identity guard:
+// a negated or compared `.id`, or a `groupIds` / `roles` check. Reading
+// `useUser().id` purely as a VALUE (the USER-column write pattern) is NOT a
+// guard, which is why an operator has to follow it.
+//
+// Conservative on purpose: an unrelated `.id` comparison elsewhere in the
+// source silences the rule. A warning that occasionally stays quiet is far
+// cheaper than one that cries wolf on correct code.
+const _IDENTITY_GUARD_RES = [
+  // `!user.id` / `!user?.id`
+  /![\s(]*\w+\??\.id\b/,
+  // `user.id ?` / `&&` / `||` / `===` / `!==` / `==` / `!=`
+  /\w+\??\.id\s*(\?[^.]|&&|\|\||===|!==|==|!=)/,
+  // any group / role check the brief asked for
+  /\bgroupIds\b/,
+  /\broles\b/,
+];
+
+function _writeGatedOnUserRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "write-not-gated-on-user",
+      severity: "warning",
+      // Kept under ~210 chars: a finding is truncated at 300 downstream, and
+      // the fix instruction is the half worth keeping.
+      label:
+        `writes with useDatastoreMutation() but never checks who is signed ` +
+        `in - read useUser(), and when !user.id render the action inactive ` +
+        `with a "sign in" line instead of a live button that can only fail.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _hardcodedCurrencyLabelRules(source) {
   const code = _stripNonCode(source, { keepStrings: true });
   if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
@@ -1201,6 +1244,7 @@ export function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js"
   },
   "engines": {
     "node": ">=18"