@colixsystems/widget-sdk 0.135.0 → 0.137.0

package/README.md

@@ -70,7 +70,65 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.135.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.137.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.137.0 (contract 1.106.0)
+
+**A `datastoreTemplate` column marked `encrypted` is now actually encrypted in the workspace that installs you (sc-7557).** The field was documented nowhere and honoured nowhere: install built its column rows one way, the republish/upgrade migration built them another way, and neither carried the flag — so a column you declared confidential was created as an ordinary plaintext column and nothing told you or your installer. Both paths now share one projection, so the flag lands on install and on upgrade alike.
+
+```js
+datastoreTemplate: {
+  tables: [
+    {
+      suffix: "Patients",
+      columns: [
+        { name: "Name", dataType: "STRING", required: true },
+        { name: "Ssn", dataType: "STRING", required: true, encrypted: true },
+      ],
+      rows: [{ Name: "Ada Lovelace", Ssn: "600101-1234" }],
+    },
+  ],
+}
+```
+
+- **Your widget code does not change.** It reads and writes plaintext through `useDatastoreQuery` / `useDatastoreMutation` exactly as it does for any other column — the platform encrypts on write (AES-256-GCM under a per-workspace subkey) and decrypts for end users.
+- **Studio users see `🔒`, not the value.** That is the point of the flag: the people authoring the app cannot read what their end users store. The column also cannot be searched, filtered or sorted on — ciphertext is opaque.
+- **Sample `rows` are encrypted too.** They used to be written straight into the value table; a plaintext row under an encrypted column would have been read back as a corrupt envelope.
+- **Not valid on `RELATION`.** Its value is a foreign key the backend has to resolve, so it can never be opaque — declaring it is now a publish error, as is a non-boolean `encrypted`.
+- **An upgrade adds a new encrypted column, but never flips a live one.** Turning encryption on over existing plaintext (or off over existing ciphertext) would strand what is already stored, so a changed flag on a column that already exists is reported back to you rather than applied.
+
+### What's new in 0.136.0 (contract 1.105.0)
+
+**A `datastoreTemplate` can now say WHICH AUDIENCE gets which access — not just the two anonymous ones (sc-7530).** `publicGrant` could only ever reach `everyone` and `authenticated`, because those are the two principals that need no id. Anything naming a real user group was unexpressible: a group id belongs to the workspace that installs your widget, so it could never travel in your manifest. The practical cost was that a permission model you had already set up correctly — say an admin group with full CRUD while ordinary signed-in users only read — shipped to your installers as nothing at all, and every one of them rebuilt it by hand across both the table grant and the record permissions.
+
+Templates now name their audiences symbolically and let the installer bind them:
+
+```js
+datastoreTemplate: {
+  roles: [
+    { key: "admin", label: "Administrators", description: "Manages orders end to end" },
+  ],
+  tables: [
+    {
+      suffix: "Orders",
+      columns: [...],
+      // the id-less audiences, unchanged
+      publicGrant: { canRead: true, canWrite: false, canDelete: false },
+      // the audience that needs a real group
+      roleGrants: [{ role: "admin", canRead: true, canWrite: true, canDelete: true }],
+    },
+  ],
+}
+```
+
+`roles` is declared ONCE per template and referenced by every table, so three widgets over two tables ask the installing workspace **one** question per audience rather than one per grant. At install they pick one of their own groups for each role, or have one created for them under the role's label.
+
+- **`key`** is lowercase-kebab (`/^[a-z][a-z0-9-]*$/`), at most 8 roles per template. A `roleGrants` entry naming a role you did not declare is a publish error, as is granting the same role twice on one table or granting it no verb at all.
+- **`canDelete` is row-level only.** A table-scope grant answers "may I create a record"; only a record permission answers a question about a row. Both halves are written for you from the one declaration.
+- **An unbound role is an ordinary outcome, never a failed install.** If the installer skips a role, no grant is written and they are told which role is still unbound — they can bind it later from the table's permissions.
+- **Purely additive.** A template declaring neither `roles` nor `roleGrants` behaves exactly as it does today.
+
+Also tightened in this release: the `publicGrant` flags are now type-checked. They never were, so a stringy `canRead: "false"` read as truthy and silently opened the table to anonymous reads. If you have been passing anything but a real boolean there, publishing will now tell you.
 
 ### What's new in 0.135.0 (contract 1.104.0)
 

package/dist/contract.cjs

@@ -2153,7 +2153,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -3913,7 +3913,20 @@ const CONTRACT = deepFreeze({
   // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
   // export and gated behind the `nfc` export capability, because its iOS
   // entitlement obliges every App ID that carries it.
-  version: "1.104.0",
+  // 1.105.0: additive (sc-7530) — a `datastoreTemplate` can declare the
+  //    AUDIENCES its tables grant access to, not just the two id-less ones.
+  //    `publicGrant` could only ever reach `everyone` and `authenticated`, so a
+  //    widget whose author had set up "an admin group does everything, signed-in
+  //    users only read" shipped that model to nobody: a group id is tenant-local
+  //    and cannot travel in a manifest. Templates now declare `roles:
+  //    [{ key, label, description? }]` once (lowercase-kebab key, max 8) and
+  //    per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`; the
+  //    installing workspace binds each role to one of ITS OWN user groups — or
+  //    has one created — during the install consent step. Purely additive: a
+  //    template declaring neither behaves exactly as before, and a role nobody
+  //    binds writes no grant rather than failing the install. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.106.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2153,7 +2153,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -3913,7 +3913,20 @@ const CONTRACT = deepFreeze({
   // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
   // export and gated behind the `nfc` export capability, because its iOS
   // entitlement obliges every App ID that carries it.
-  version: "1.104.0",
+  // 1.105.0: additive (sc-7530) — a `datastoreTemplate` can declare the
+  //    AUDIENCES its tables grant access to, not just the two id-less ones.
+  //    `publicGrant` could only ever reach `everyone` and `authenticated`, so a
+  //    widget whose author had set up "an admin group does everything, signed-in
+  //    users only read" shipped that model to nobody: a group id is tenant-local
+  //    and cannot travel in a manifest. Templates now declare `roles:
+  //    [{ key, label, description? }]` once (lowercase-kebab key, max 8) and
+  //    per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`; the
+  //    installing workspace binds each role to one of ITS OWN user groups — or
+  //    has one created — during the install consent step. Purely additive: a
+  //    template declaring neither behaves exactly as before, and a role nobody
+  //    binds writes no grant rather than failing the install. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.106.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -186,6 +186,15 @@ export interface WidgetDatastoreTemplateColumn {
   relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY";
   /** REQ-ACL-RELINHERIT: opt this RELATION column into row-level ACL inheritance. */
   inheritAcl?: boolean;
+  /**
+   * REQ-DDL-ENCRYPT: store this column's values encrypted at rest (AES-256-GCM
+   * under a per-workspace subkey). The widget still reads and writes plaintext
+   * — the platform encrypts on write and decrypts for end users — but studio
+   * users see `🔒` instead of the value, and the column cannot be searched,
+   * filtered or sorted on. Not valid on `RELATION` (its value is a foreign key
+   * the backend must resolve); publishing one is rejected.
+   */
+  encrypted?: boolean;
 }
 
 export interface WidgetDatastoreTemplateTable {
@@ -201,6 +210,14 @@ export interface WidgetDatastoreTemplateTable {
    * studio-owner only regardless.
    */
   publicGrant?: { canRead?: boolean; canWrite?: boolean; canDelete?: boolean };
+  /**
+   * sc-7530: group-scoped grants, named symbolically. Each entry's `role` must
+   * be a `key` declared on the template's `roles`. Unlike `publicGrant` — which
+   * can only reach the two synthetic principals (`everyone` / `authenticated`)
+   * — these express "this audience gets these verbs" and are bound to a real
+   * group by the workspace that installs the widget.
+   */
+  roleGrants?: WidgetDatastoreTemplateRoleGrant[];
   columns: WidgetDatastoreTemplateColumn[];
   /**
    * Optional sample rows seeded into the table at install time so the widget
@@ -213,8 +230,44 @@ export interface WidgetDatastoreTemplateTable {
   >;
 }
 
+/**
+ * sc-7530: a role the template's `roleGrants` name. Declared once per template
+ * and referenced by every table, so several widgets over several tables ask the
+ * installing workspace ONE question per audience rather than one per grant.
+ *
+ * Symbolic on purpose. A group id is tenant-local, so it could only ever be
+ * wrong in the workspace that installs the widget — the installer binds each
+ * role to one of their OWN groups (or has one created) at install time.
+ */
+export interface WidgetDatastoreTemplateRole {
+  /** Stable within the template; matches /^[a-z][a-z0-9-]*$/. */
+  key: string;
+  /** What the installing workspace sees in the binding step. */
+  label: string;
+  /** Why the role exists — shown under the label. */
+  description?: string;
+}
+
+/** sc-7530: the verbs one role holds over one table. */
+export interface WidgetDatastoreTemplateRoleGrant {
+  /** A `key` from the template's `roles`. */
+  role: string;
+  /** Read the table and the rows in it. */
+  canRead?: boolean;
+  /** Create records, and edit existing ones. */
+  canWrite?: boolean;
+  /** Delete records. Row-level only — table scope has no delete verb. */
+  canDelete?: boolean;
+}
+
 export interface WidgetDatastoreTemplate {
   tables: WidgetDatastoreTemplateTable[];
+  /**
+   * sc-7530: the audiences this template's tables grant access to. Bound to
+   * real `AppUserGroup`s by the installing workspace; an unbound role simply
+   * writes no grant.
+   */
+  roles?: WidgetDatastoreTemplateRole[];
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.135.0",
+  "version": "0.137.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",