@colixsystems/widget-sdk 0.17.0 → 0.18.0

package/README.md

@@ -6,9 +6,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.17.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.18.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.17.0
+### What's new in 0.18.0
+
+REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission management from inside a widget.
+
+- **`useRecordPermissions(tableId, recordId)` is wired** + the new `WidgetContext.recordPermissions` slice + the new `acl.write:records` scope. Returns `{ permissions, loading, error, grant, revoke, update, refetch }` where `permissions` is `Array<{ id, principalType: "USER" | "GROUP" | "PUBLIC", principalId, canRead, canWrite, canDelete, canGrant }>`. Hits the existing REQ-ACL-06 `/api/v1/tables/:tableId/records/:recordId/permissions` REST surface; the host normalises the wire shape (`userId` / `groupId`) into the `principalType` + `principalId` pair the hook returns. Rejections from `grant` / `revoke` / `update` surface as a new structured `PermissionError` (named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | CONFLICT | INTERNAL`. When `tableId` or `recordId` is null/empty the hook collapses to a stable empty no-op result without a network round-trip. Mutating requires `acl.write:records` AND `canGrant` on the target record — Studio owners short-circuit, APP_USER actors hold `canGrant` via REQ-ACL-05 (creator-grant) or a delegated REQ-ACL-06 grant. Backs the rewritten built-in Chat widget's "+ New channel" + DM-create flows, where the channel creator grants `canRead` / `canWrite` / `canGrant` to each invitee without going through Studio. Additive.
+- **`CONTRACT.version` → `1.8.0`** (additive: one new hook, one new context slice, one new scope, one new error class). No existing export changed signature.
+
+### What was in 0.17.0
 
 REQ-WBLT-FORMBUILDER — a runtime schema resolver so widgets can render by column type.
 
@@ -132,7 +139,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (structure only, no row data) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (structure only, no row data) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`, `DateTimePicker` wraps `@react-native-community/datetimepicker`). The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
@@ -184,6 +191,59 @@ The matching manifest declares the scopes:
 
 The host rejects calls whose scope is not declared in the manifest (the SDK linter catches this statically too). Declaring a write scope is also a consent prompt the Studio admin sees at install time — the wider the scope set, the more careful the admin is about granting the install.
 
+## Managing per-record permissions from a widget
+
+REQ-ACL-06 / REQ-ACL-RELINHERIT-05 added `useRecordPermissions(tableId, recordId)`, the in-app surface for sharing a single record with another user or group. The chat widget uses it to invite members into a channel — the channel record's per-record grants ARE the membership list (Messages inherit those grants via REQ-ACL-RELINHERIT). The hook also covers project-workspace, document-sharing, and team-roster widgets that grant access on a record-by-record basis.
+
+```js
+import { Text, View, Pressable, useRecordPermissions, PermissionError } from "@colixsystems/widget-sdk";
+
+export default function ShareRecord({ tableId, recordId, partnerUserId }) {
+  const { permissions, loading, grant, revoke } = useRecordPermissions(tableId, recordId);
+  if (loading) return <Text>Loading members…</Text>;
+  return (
+    <View>
+      {permissions.map((p) => (
+        <View key={p.id}>
+          <Text>{p.principalType}:{p.principalId} — {p.canWrite ? "writer" : "reader"}</Text>
+          <Pressable onPress={() => revoke(p.id)}><Text>Remove</Text></Pressable>
+        </View>
+      ))}
+      <Pressable
+        onPress={async () => {
+          try {
+            await grant({
+              principalType: "USER",
+              principalId: partnerUserId,
+              canRead: true,
+              canWrite: true,
+              canGrant: true,
+            });
+          } catch (err) {
+            if (err instanceof PermissionError && err.code === "FORBIDDEN") {
+              // The signed-in user lacks canGrant on this record.
+            }
+          }
+        }}
+      >
+        <Text>Invite partner</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+The manifest declares the matching scope:
+
+```js
+{
+  // ...
+  requestedScopes: ["acl.write:records"],
+}
+```
+
+The server-side gate is `canGrant` on the target record — Studio owners short-circuit, and APP_USER actors who hold `canGrant` (via REQ-ACL-05 creator-grant, or a delegated REQ-ACL-06 grant) pass. A caller without `canGrant` receives `PermissionError { code: "FORBIDDEN" }`. The hook collapses to a stable no-op when `tableId` or `recordId` is null/empty — so a widget can render its picker first, then bind to the picked record without any conditional hook tricks.
+
 ## Linter
 
 ```sh

package/dist/contract.cjs

@@ -264,6 +264,41 @@ const HOOKS = [
     ],
     scopes: ["groups.read:*"],
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management for a single record. Mirror of contract.js.
+  {
+    name: "useRecordPermissions",
+    signature: "useRecordPermissions(tableId, recordId)",
+    description:
+      "Manage per-record VirtualPermission grants on a single record. Returns " +
+      "{ permissions, loading, error, grant, revoke, update, refetch } where " +
+      "permissions is Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', " +
+      "principalId, canRead, canWrite, canDelete, canGrant }>. Mutating " +
+      "requires acl.write:records scope AND canGrant on the target record " +
+      "(REQ-ACL-RELINHERIT-05: APP_USER actors with canGrant are accepted, " +
+      "not only Studio owners). When tableId or recordId is null/empty the " +
+      "hook collapses to an empty no-op result without a network round-trip.",
+    returnShape: {
+      permissions:
+        "Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', principalId, canRead, canWrite, canDelete, canGrant }>",
+      loading: "boolean",
+      error: "PermissionError | null",
+      grant:
+        "({ principalType, principalId?, canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      revoke:
+        "(permissionId) => Promise<void>  // rejects with PermissionError",
+      update:
+        "(permissionId, { canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: [
+      "recordPermissions.list",
+      "recordPermissions.grant",
+      "recordPermissions.revoke",
+      "recordPermissions.update",
+    ],
+    scopes: ["acl.write:records"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -596,6 +631,26 @@ const WIDGET_CONTEXT_SHAPE = {
       remove: "function",
     },
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management facade backing useRecordPermissions(). Mirror of
+  // contract.js.
+  recordPermissions: {
+    description:
+      "Per-record VirtualPermission management. " +
+      "{ list(tableId, recordId) -> Promise<RecordPermission[]>, " +
+      "grant(tableId, recordId, body) -> Promise<RecordPermission>, " +
+      "revoke(tableId, recordId, permissionId) -> Promise<void>, " +
+      "update(tableId, recordId, permissionId, body) -> Promise<RecordPermission> }. " +
+      "Backs useRecordPermissions(); requires acl.write:records scope AND " +
+      "canGrant on the target record.",
+    required: true,
+    fields: {
+      list: "function",
+      grant: "function",
+      revoke: "function",
+      update: "function",
+    },
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
   // backing useGroups(). Reads gated by `groups.read:*`; mutations by
   // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
@@ -865,7 +920,15 @@ const CONTRACT = deepFreeze({
   // stored columnId to its column name / dataType / relation target at
   // runtime (Form Builder renders inputs by column type). Reads the existing
   // ACL-gated `GET /tables/:id` — structure only, no row data.
-  version: "1.7.0",
+  //
+  // 1.8.0: additive — new `useRecordPermissions(tableId, recordId)` hook +
+  // the `recordPermissions` host-context slice it reads + the
+  // `acl.write:records` scope it gates on. Hits the existing REQ-ACL-06
+  // /api/v1/tables/:tableId/records/:recordId/permissions REST surface; the
+  // host normalises the wire shape into a single principalType+principalId
+  // pair widgets branch on. Caller still needs canGrant on the target
+  // record (REQ-ACL-RELINHERIT-05).
+  version: "1.8.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -265,6 +265,47 @@ const HOOKS = [
     ],
     scopes: ["groups.read:*"],
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management for a single record. Reads `ctx.recordPermissions` (the
+  // host injects this on web through `widgetHostDatastore.js` and on
+  // native through the compiled `WidgetHost` shell). The backend gates
+  // the call on `canGrant` for the target record (Studio owners short-
+  // circuit; APP_USER actors must hold `canGrant` via REQ-ACL-05 /
+  // REQ-ACL-06). A widget that declares the scope but whose caller
+  // lacks the grant receives `PermissionError { code: 'FORBIDDEN' }`.
+  {
+    name: "useRecordPermissions",
+    signature: "useRecordPermissions(tableId, recordId)",
+    description:
+      "Manage per-record VirtualPermission grants on a single record. Returns " +
+      "{ permissions, loading, error, grant, revoke, update, refetch } where " +
+      "permissions is Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', " +
+      "principalId, canRead, canWrite, canDelete, canGrant }>. Mutating " +
+      "requires acl.write:records scope AND canGrant on the target record " +
+      "(REQ-ACL-RELINHERIT-05: APP_USER actors with canGrant are accepted, " +
+      "not only Studio owners). When tableId or recordId is null/empty the " +
+      "hook collapses to an empty no-op result without a network round-trip.",
+    returnShape: {
+      permissions:
+        "Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', principalId, canRead, canWrite, canDelete, canGrant }>",
+      loading: "boolean",
+      error: "PermissionError | null",
+      grant:
+        "({ principalType, principalId?, canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      revoke:
+        "(permissionId) => Promise<void>  // rejects with PermissionError",
+      update:
+        "(permissionId, { canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: [
+      "recordPermissions.list",
+      "recordPermissions.grant",
+      "recordPermissions.revoke",
+      "recordPermissions.update",
+    ],
+    scopes: ["acl.write:records"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks.
   {
     name: "useClipboard",
@@ -590,6 +631,28 @@ const WIDGET_CONTEXT_SHAPE = {
       remove: "function",
     },
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management facade backing useRecordPermissions(). Hits the existing
+  // /api/v1/tables/:tableId/records/:recordId/permissions REST surface;
+  // the host normalises the wire shape (userId / groupId / both-null =
+  // public) into the principalType+principalId pair widgets read.
+  recordPermissions: {
+    description:
+      "Per-record VirtualPermission management. " +
+      "{ list(tableId, recordId) -> Promise<RecordPermission[]>, " +
+      "grant(tableId, recordId, body) -> Promise<RecordPermission>, " +
+      "revoke(tableId, recordId, permissionId) -> Promise<void>, " +
+      "update(tableId, recordId, permissionId, body) -> Promise<RecordPermission> }. " +
+      "Backs useRecordPermissions(); requires acl.write:records scope AND " +
+      "canGrant on the target record.",
+    required: true,
+    fields: {
+      list: "function",
+      grant: "function",
+      revoke: "function",
+      update: "function",
+    },
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
   // backing useGroups(). Reads gated by `groups.read:*`; mutations by
   // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
@@ -810,10 +873,14 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  // 1.7.0: additive — new useDatastoreSchema(tableId) hook + the
-  // datastore.schema host-context slice it reads (resolves a table's column
-  // structure at runtime via the existing ACL-gated GET /tables/:id).
-  version: "1.7.0",
+  // 1.8.0: additive — new useRecordPermissions(tableId, recordId) hook +
+  // the recordPermissions host-context slice it reads + the
+  // acl.write:records scope it gates on. Hits the existing REQ-ACL-06
+  // /api/v1/tables/:tableId/records/:recordId/permissions REST surface;
+  // the host normalises the wire shape into a single principalType+
+  // principalId pair widgets branch on. Caller still needs canGrant on
+  // the target record (REQ-ACL-RELINHERIT-05).
+  version: "1.8.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -994,6 +994,232 @@ export function useGroups(query) {
   return { groups, loading, error, refetch, create, remove, addMember, removeMember };
 }
 
+/**
+ * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — structured error thrown by
+ * `useRecordPermissions` mutation callbacks (and surfaced by the hook's
+ * `error` slot when the initial list fetch fails). Carries a stable
+ * `code` so widgets can branch on the error class without parsing
+ * message strings; mirrors the shape of `DirectoryError`.
+ *
+ * `code` is one of:
+ *   - "FORBIDDEN"  — 403 from the host (caller lacks canGrant on the record).
+ *   - "VALIDATION" — 400 / 422 (missing principal, malformed body).
+ *   - "NOT_FOUND"  — 404 (record absent, cross-tenant, or permission row
+ *                    not found on revoke/update).
+ *   - "CONFLICT"   — 409 (e.g. trying to edit a template-derived row).
+ *   - "INTERNAL"   — anything else (network, 5xx).
+ */
+export class PermissionError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "PermissionError";
+    this.code = code;
+    if (opts && opts.status !== undefined) this.status = opts.status;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toPermissionError(err) {
+  if (err instanceof PermissionError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyCode =
+    err && err.response && err.response.data && err.response.data.code;
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  else if (status === 409) code = "CONFLICT";
+  else if (status === 400 || status === 422) code = "VALIDATION";
+  if (typeof bodyCode === "string" && bodyCode) {
+    // Preserve the server's stable code over the status-derived one when
+    // the server volunteered it (e.g. TEMPLATE_DERIVED on edit/delete of
+    // an inherit/template row).
+    code = bodyCode;
+  }
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Record permission call failed");
+  return new PermissionError(code, message, { status, cause: err });
+}
+
+const _NOOP_PERMISSIONS_RESULT = Object.freeze({
+  permissions: [],
+  loading: false,
+  error: null,
+  // Mutation no-ops resolve with null so a widget that does
+  // `await grant(...)` doesn't crash when called against an unbound
+  // (tableId / recordId null) hook.
+  grant: async () => null,
+  revoke: async () => undefined,
+  update: async () => null,
+  refetch: async () => undefined,
+});
+
+/**
+ * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — manage per-record VirtualPermission
+ * grants on a single record. Returns
+ * `{ permissions, loading, error, grant, revoke, update, refetch }`.
+ *
+ * `permissions` is an array of rows:
+ *   `{ id, principalType: "USER" | "GROUP" | "PUBLIC", principalId, canRead, canWrite, canDelete, canGrant }`.
+ *
+ * The host's `ctx.recordPermissions` facade exposes:
+ *   - `list(tableId, recordId)` → `Promise<row[]>`
+ *   - `grant(tableId, recordId, body)` → `Promise<row>`
+ *   - `revoke(tableId, recordId, permissionId)` → `Promise<void>`
+ *   - `update(tableId, recordId, permissionId, body)` → `Promise<row>`
+ *
+ * The hook normalises the wire shape (`userId` / `groupId` / both-null =
+ * public) into a single `{ principalType, principalId }` pair that
+ * widgets can branch on without knowing the backend's column names.
+ *
+ * When `tableId` OR `recordId` is null / undefined / empty (e.g. the
+ * widget hasn't picked an active channel yet), the hook collapses to a
+ * stable empty result without a network round-trip. Mutation methods
+ * are safe no-ops in that state so a widget can call them
+ * unconditionally.
+ *
+ * Requires the `acl.write:records` scope in the widget manifest's
+ * `requestedScopes`. The underlying REST endpoint gates the call on
+ * `canGrant` for the target record (Studio owners short-circuit;
+ * APP_USER actors must hold `canGrant` via REQ-ACL-05 / REQ-ACL-06).
+ * A widget that declares the scope but whose caller lacks the grant
+ * receives `PermissionError { code: "FORBIDDEN" }`.
+ */
+export function useRecordPermissions(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useRecordPermissions");
+  if (
+    !ctx.recordPermissions ||
+    typeof ctx.recordPermissions.list !== "function" ||
+    typeof ctx.recordPermissions.grant !== "function" ||
+    typeof ctx.recordPermissions.revoke !== "function" ||
+    typeof ctx.recordPermissions.update !== "function"
+  ) {
+    throw new Error(
+      "useRecordPermissions: host did not inject a recordPermissions client",
+    );
+  }
+  const ready = Boolean(tableId && recordId);
+  const [permissions, setPermissions] = useState([]);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  // Same ref discipline as useDirectory / useDatastoreQuery — the host
+  // rebuilds the WidgetContext value every render, so we capture the
+  // live ids + client in refs to keep refetch + grant + revoke + update
+  // stable callback identities.
+  const tableIdRef = useRef(tableId);
+  const recordIdRef = useRef(recordId);
+  const clientRef = useRef(ctx.recordPermissions);
+  tableIdRef.current = tableId;
+  recordIdRef.current = recordId;
+  clientRef.current = ctx.recordPermissions;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const t = tableIdRef.current;
+    const r = recordIdRef.current;
+    if (!t || !r) {
+      // Collapse to a stable empty result without a network round-trip
+      // so a widget rendering before an active record is picked stays
+      // loop-free.
+      setLoading(false);
+      setError(null);
+      setPermissions([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await clientRef.current.list(t, r);
+      if (runRef.current !== myRun) return;
+      setPermissions(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toPermissionError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!ready) {
+      // Reset the slot when the widget unbinds (e.g. user navigates
+      // back to the picker) so the next render doesn't show stale
+      // permissions from a previous record.
+      setPermissions([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tableId, recordId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const grant = useCallback(async (body) => {
+    const t = tableIdRef.current;
+    const r = recordIdRef.current;
+    if (!t || !r) return null;
+    try {
+      const row = await clientRef.current.grant(t, r, body);
+      // Refresh after the mutation so subsequent reads observe the
+      // grant. The host's facade returns the created row too, which we
+      // hand back to the caller for inline use.
+      await doFetch();
+      return row;
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [doFetch]);
+
+  const revoke = useCallback(async (permissionId) => {
+    const t = tableIdRef.current;
+    const r = recordIdRef.current;
+    if (!t || !r) return undefined;
+    try {
+      await clientRef.current.revoke(t, r, permissionId);
+      await doFetch();
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [doFetch]);
+
+  const update = useCallback(async (permissionId, body) => {
+    const t = tableIdRef.current;
+    const r = recordIdRef.current;
+    if (!t || !r) return null;
+    try {
+      const row = await clientRef.current.update(t, r, permissionId, body);
+      await doFetch();
+      return row;
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [doFetch]);
+
+  if (!ready) {
+    // Mutation no-ops are safe: a widget that does
+    // `await grant({...})` against an unbound hook resolves to null
+    // rather than throwing. Same shape as the populated case so the
+    // caller can branch on `tableId/recordId` once, at the top.
+    return _NOOP_PERMISSIONS_RESULT;
+  }
+
+  return { permissions, loading, error, grant, revoke, update, refetch };
+}
+
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
   const i18n = ctx.i18n || {};

package/dist/index.d.ts

@@ -642,6 +642,98 @@ export interface GroupsApi {
  */
 export function useGroups(query?: GroupsQuery): GroupsApi;
 
+// ----------------------------------------------------- useRecordPermissions
+//
+// REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+// management for a single record. Reuses the existing
+// `/api/v1/tables/:tableId/records/:recordId/permissions` REST surface;
+// the host normalises the wire shape (`userId` / `groupId` /
+// both-null = public) into the `{ principalType, principalId }` pair
+// returned to widgets so the call site is portable.
+
+export interface RecordPermission {
+  id: string;
+  principalType: "USER" | "GROUP" | "PUBLIC";
+  /** `null` when `principalType === "PUBLIC"`. */
+  principalId: string | null;
+  canRead: boolean;
+  canWrite: boolean;
+  canDelete: boolean;
+  canGrant: boolean;
+}
+
+export interface RecordPermissionGrantInput {
+  /** Either a concrete principal (`USER` / `GROUP`) or `"PUBLIC"`. */
+  principalType: "USER" | "GROUP" | "PUBLIC";
+  /** Required when `principalType !== "PUBLIC"`. */
+  principalId?: string | null;
+  canRead?: boolean;
+  canWrite?: boolean;
+  canDelete?: boolean;
+  canGrant?: boolean;
+}
+
+export interface RecordPermissionUpdateInput {
+  canRead?: boolean;
+  canWrite?: boolean;
+  canDelete?: boolean;
+  canGrant?: boolean;
+}
+
+export interface RecordPermissionsResult {
+  permissions: RecordPermission[];
+  loading: boolean;
+  error: PermissionError | null;
+  /**
+   * Grant a new permission on the active record. Resolves to the created
+   * row. Rejects with `PermissionError` on HTTP failure.
+   */
+  grant(body: RecordPermissionGrantInput): Promise<RecordPermission | null>;
+  /** Revoke an existing permission row. Rejects with `PermissionError`. */
+  revoke(permissionId: string): Promise<void>;
+  /**
+   * Patch the flags on an existing permission row. Resolves to the
+   * updated row. Rejects with `PermissionError`.
+   */
+  update(
+    permissionId: string,
+    body: RecordPermissionUpdateInput,
+  ): Promise<RecordPermission | null>;
+  refetch(): Promise<void>;
+}
+
+export class PermissionError extends Error {
+  code:
+    | "FORBIDDEN"
+    | "VALIDATION"
+    | "NOT_FOUND"
+    | "CONFLICT"
+    | "INTERNAL"
+    | string;
+  status?: number;
+  constructor(
+    code: PermissionError["code"],
+    message: string,
+    opts?: { status?: number; cause?: unknown },
+  );
+}
+
+/**
+ * REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+ * management. Requires `acl.write:records` in the manifest's
+ * `requestedScopes`. The backend gates the call on `canGrant` for the
+ * target record; a widget that declares the scope but whose caller
+ * lacks the grant receives `PermissionError { code: "FORBIDDEN" }`.
+ *
+ * When `tableId` OR `recordId` is null / empty, the hook collapses to a
+ * stable empty result without a network round-trip; mutation methods
+ * are safe no-ops in that state.
+ */
+export function useRecordPermissions(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): RecordPermissionsResult;
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;

package/dist/index.js

@@ -10,6 +10,7 @@ export {
   DatastoreError,
   PaymentError,
   DirectoryError,
+  PermissionError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -18,6 +19,7 @@ export {
   useDirectory,
   useUsers,
   useGroups,
+  useRecordPermissions,
   useWidgetEvent,
   usePayments,
   useTheme,

package/dist/index.native.js

@@ -10,6 +10,7 @@ export {
   DatastoreError,
   PaymentError,
   DirectoryError,
+  PermissionError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -18,6 +19,7 @@ export {
   useDirectory,
   useUsers,
   useGroups,
+  useRecordPermissions,
   useWidgetEvent,
   usePayments,
   useTheme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,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__/linter-users-scope.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-record-permissions.test.js src/__tests__/linter-users-scope.test.js"
   },
   "engines": {
     "node": ">=18"