@colixsystems/widget-sdk 0.13.0 → 0.14.1

package/README.md

@@ -6,7 +6,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.13.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.14.1` — 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.14.1
+
+- **`groupRef` property type (REQ-USERMGMT M4 / §4.8).** Authors can now declare `{ type: 'groupRef', label: 'Group' }` in their `propertySchema` to render a Group picker in the Studio Properties Panel. The widget receives a bare `AppUserGroup` UUID — REQ-GEN-07 compliant, so tenant-copy walks the value transparently. Used by the built-in `appstudio.user-management` widget for its `defaultGroupId` prop and available to third-party widgets that need to anchor behaviour on a specific group.
+- **Patch bump** — additive enumeration entry, no exported function signature changed. `CONTRACT.version` stays `1.4.0`.
+
+### What's new in 0.14.0
+
+- **`useUsers()` + `useGroups()` — AppUser administration hooks (REQ-USERMGMT / REQ-ACL-SYS M3).** A widget can now invite, deactivate, reactivate, and remove members, and create / delete groups + add / remove members, from a published-app surface. Returns `{ users | groups, loading, error, refetch, ... }` plus imperative mutation methods. Reads gated by `users.read:*` / `groups.read:*`; mutations by `users.write:*` / `groups.write:*`. Rejections surface as a structured `DirectoryError` (new named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY`. The host signs an `X-Widget-Scopes` header against `JWT_SECRET` so an APP_USER cannot forge a scope set, and the backend additionally gates the request behind a SystemAcl `users.*` / `groups.*` capability grant (REQ-ACL-SYS M1 + M3).
+- **Managing app users from a widget — see the section below.**
+- **New linter rule `no-scope-mismatch-useUsers` / `no-scope-mismatch-useGroups`.** Calling `useUsers().invite()` / `.deactivate()` / `.reactivate()` / `.remove()` without `users.write:*` in the manifest's `requestedScopes` fails the lint; calling `useGroups()` mutation methods without `groups.write:*` fails the lint. Keeps the manifest honest at submission time.
+- **`CONTRACT.version` → `1.4.0`** (additive: two new hooks, two new context slices, six new scope verbs, one new error class). No existing export changed signature.
 
 ### What's new in 0.13.0
 
@@ -89,11 +101,58 @@ 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`, `useDatastoreMutation`, `useDirectory`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `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). `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`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer` — hooks that read from the host-provided `WidgetContext`. `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). `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` — re-exported from `react-native`. 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. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
+## Managing app users from a widget
+
+REQ-USERMGMT / REQ-ACL-SYS M3 added two hooks that let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. The hooks are gated by two layers: the widget's manifest must declare the scope (so the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability in the tenant (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller does not hold the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that to the end-user as a "you do not have permission to do that" message.
+
+```js
+import { Text, View, Pressable, useUsers, useGroups } from "@colixsystems/widget-sdk";
+
+export default function MemberManager() {
+  const { users, loading, invite, deactivate, remove } = useUsers({ q: "" });
+  const { groups, addMember } = useGroups();
+  if (loading) return <Text>Loading…</Text>;
+  return (
+    <View>
+      {users.map((u) => (
+        <View key={u.id}>
+          <Text>{u.name} — {u.isActive ? "active" : "inactive"}</Text>
+          <Pressable onPress={() => deactivate(u.id)}><Text>Deactivate</Text></Pressable>
+          <Pressable onPress={() => remove(u.id)}><Text>Remove</Text></Pressable>
+        </View>
+      ))}
+      <Pressable
+        onPress={async () => {
+          try {
+            await invite({ email: "a@b.com", name: "New User", groupIds: [groups[0]?.id].filter(Boolean) });
+          } catch (err) {
+            // err.code is one of FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY
+          }
+        }}
+      >
+        <Text>Invite</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+The matching manifest declares the scopes:
+
+```js
+{
+  // ...
+  requestedScopes: ["users.read:*", "users.write:*", "groups.read:*", "groups.write:*"],
+}
+```
+
+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.
+
 ## Linter
 
 ```sh

package/dist/contract.cjs

@@ -170,6 +170,76 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
+  // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
+  // Reads need `users.read:*` scope; mutations additionally need
+  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
+  // and returns the resulting AppUserInvite row (the email is sent by the
+  // host). Mutating users from a widget requires the corresponding
+  // SystemAcl `users.write` capability grant in the tenant; widgets that
+  // only call read methods need only `users.read:*`.
+  {
+    name: "useUsers",
+    signature: "useUsers(query?)",
+    description:
+      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
+      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
+      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
+      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+    returnShape: {
+      users: "Array<{ id, name, email?, role, isActive }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      invite:
+        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+      deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "users.listUsers",
+      "users.invite",
+      "users.deactivate",
+      "users.reactivate",
+      "users.remove",
+    ],
+    scopes: ["users.read:*"],
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
+  // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
+  // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
+  // member requires the corresponding `users.write` capability since it
+  // affects the user's effective access.
+  {
+    name: "useGroups",
+    signature: "useGroups(query?)",
+    description:
+      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
+      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "mutations need groups.write:*.",
+    returnShape: {
+      groups: "Array<{ id, name, memberCount }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      create:
+        "({ name }) => Promise<Group>  // rejects with DirectoryError",
+      remove: "(groupId) => Promise<void>  // rejects with DirectoryError",
+      addMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+      removeMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "groups.listGroups",
+      "groups.create",
+      "groups.remove",
+      "groups.addMember",
+      "groups.removeMember",
+    ],
+    scopes: ["groups.read:*"],
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -433,6 +503,38 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
+  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
+  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
+  // APP_USER cannot forge scope claims, and the request is additionally
+  // gated by a SystemAcl `users.read` / `users.write` capability grant.
+  users: {
+    description:
+      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
+    required: true,
+    fields: {
+      listUsers: "function",
+      invite: "function",
+      deactivate: "function",
+      reactivate: "function",
+      remove: "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.
+  groups: {
+    description:
+      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
+    required: true,
+    fields: {
+      listGroups: "function",
+      create: "function",
+      remove: "function",
+      addMember: "function",
+      removeMember: "function",
+    },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -525,7 +627,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.2.0",
+  version: "1.4.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -171,6 +171,76 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
+  // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
+  // Reads need `users.read:*` scope; mutations additionally need
+  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
+  // and returns the resulting AppUserInvite row (the email is sent by the
+  // host). Mutating users from a widget requires the corresponding
+  // SystemAcl `users.write` capability grant in the tenant; widgets that
+  // only call read methods need only `users.read:*`.
+  {
+    name: "useUsers",
+    signature: "useUsers(query?)",
+    description:
+      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
+      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
+      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
+      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+    returnShape: {
+      users: "Array<{ id, name, email?, role, isActive }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      invite:
+        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+      deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
+      remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "users.listUsers",
+      "users.invite",
+      "users.deactivate",
+      "users.reactivate",
+      "users.remove",
+    ],
+    scopes: ["users.read:*"],
+  },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
+  // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
+  // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
+  // member requires the corresponding `users.write` capability since it
+  // affects the user's effective access.
+  {
+    name: "useGroups",
+    signature: "useGroups(query?)",
+    description:
+      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
+      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "mutations need groups.write:*.",
+    returnShape: {
+      groups: "Array<{ id, name, memberCount }>",
+      loading: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      create:
+        "({ name }) => Promise<Group>  // rejects with DirectoryError",
+      remove: "(groupId) => Promise<void>  // rejects with DirectoryError",
+      addMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+      removeMember:
+        "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: [
+      "groups.listGroups",
+      "groups.create",
+      "groups.remove",
+      "groups.addMember",
+      "groups.removeMember",
+    ],
+    scopes: ["groups.read:*"],
+  },
 ];
 
 // REQ-WSDK-RN-WEB: see contract.cjs for the source-of-truth comment.
@@ -427,6 +497,38 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
+  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
+  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
+  // APP_USER cannot forge scope claims, and the request is additionally
+  // gated by a SystemAcl `users.read` / `users.write` capability grant.
+  users: {
+    description:
+      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
+    required: true,
+    fields: {
+      listUsers: "function",
+      invite: "function",
+      deactivate: "function",
+      reactivate: "function",
+      remove: "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.
+  groups: {
+    description:
+      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
+    required: true,
+    fields: {
+      listGroups: "function",
+      create: "function",
+      remove: "function",
+      addMember: "function",
+      removeMember: "function",
+    },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -517,7 +619,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.2.0",
+  version: "1.4.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -687,6 +687,236 @@ export function usePayments() {
  * the key is missing. The host's i18n.t may or may not honour the two-arg
  * form; we degrade gracefully either way.
  */
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — structured error thrown by `useUsers` /
+ * `useGroups` callbacks. Carries a stable `code` so widgets can branch
+ * without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "FORBIDDEN"   — 403 from the host (capability or scope missing).
+ *   - "VALIDATION"  — 400 / 422 (bad email, duplicate, etc.).
+ *   - "NOT_FOUND"   — 404 (group / user does not exist or cross-tenant).
+ *   - "INVITE_ONLY" — 409 from accept-invite-style flows where the tenant
+ *                     is invite-only and the email is not on the list.
+ *   - "INTERNAL"    — anything else (network, 5xx).
+ */
+export class DirectoryError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "DirectoryError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toDirectoryError(err) {
+  if (err instanceof DirectoryError) 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 (bodyCode === "INVITE_ONLY") code = "INVITE_ONLY";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 404) code = "NOT_FOUND";
+  else if (status === 400 || status === 422) code = "VALIDATION";
+  else if (status === 409) {
+    // 409 is invite-only on the invite endpoints; treat the rest as
+    // validation conflicts (duplicate email, etc.).
+    code = bodyCode === "INVITE_ONLY" ? "INVITE_ONLY" : "VALIDATION";
+  }
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Directory call failed");
+  return new DirectoryError(code, message, { cause: err });
+}
+
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
+ *
+ * Returns `{ users, loading, error, refetch, invite, deactivate,
+ * reactivate, remove }`. The list refetches whenever
+ * `JSON.stringify(query)` changes; the imperative methods reject with a
+ * `DirectoryError`. Reads require the `users.read:*` scope; mutations
+ * additionally require `users.write:*`. The host's signed
+ * `X-Widget-Scopes` header + a tenant-scoped SystemAcl `users.read` /
+ * `users.write` capability grant gate the underlying endpoint
+ * (REQ-ACL-SYS M3 §4.3) — a widget that declares the scopes but whose
+ * caller does not hold the grant gets a `FORBIDDEN`.
+ */
+export function useUsers(query) {
+  const ctx = useWidgetContextOrThrow("useUsers");
+  if (!ctx.users || typeof ctx.users.listUsers !== "function") {
+    throw new Error("useUsers: host did not inject a users client");
+  }
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const queryRef = useRef(query);
+  const usersRef = useRef(ctx.users);
+  queryRef.current = query;
+  usersRef.current = ctx.users;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await usersRef.current.listUsers(queryRef.current);
+      if (runRef.current !== myRun) return;
+      setUsers(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDirectoryError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const invite = useCallback(async (args) => {
+    try {
+      return await usersRef.current.invite(args);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const deactivate = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.deactivate(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const reactivate = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.reactivate(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const remove = useCallback(async (userId) => {
+    try {
+      return await usersRef.current.remove(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+
+  return { users, loading, error, refetch, invite, deactivate, reactivate, remove };
+}
+
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration hook.
+ *
+ * Returns `{ groups, loading, error, refetch, create, remove, addMember,
+ * removeMember }`. Reads require `groups.read:*`; mutations require
+ * `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as `useUsers`.
+ */
+export function useGroups(query) {
+  const ctx = useWidgetContextOrThrow("useGroups");
+  if (!ctx.groups || typeof ctx.groups.listGroups !== "function") {
+    throw new Error("useGroups: host did not inject a groups client");
+  }
+  const [groups, setGroups] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const queryRef = useRef(query);
+  const groupsRef = useRef(ctx.groups);
+  queryRef.current = query;
+  groupsRef.current = ctx.groups;
+
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    setLoading(true);
+    setError(null);
+    try {
+      const rows = await groupsRef.current.listGroups(queryRef.current);
+      if (runRef.current !== myRun) return;
+      setGroups(Array.isArray(rows) ? rows : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDirectoryError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  const queryKey = (() => {
+    try {
+      return JSON.stringify(query);
+    } catch (_e) {
+      return null;
+    }
+  })();
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [queryKey]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const create = useCallback(async (args) => {
+    try {
+      return await groupsRef.current.create(args);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const remove = useCallback(async (groupId) => {
+    try {
+      return await groupsRef.current.remove(groupId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const addMember = useCallback(async (groupId, userId) => {
+    try {
+      return await groupsRef.current.addMember(groupId, userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+  const removeMember = useCallback(async (groupId, userId) => {
+    try {
+      return await groupsRef.current.removeMember(groupId, userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
+
+  return { groups, loading, error, refetch, create, remove, addMember, removeMember };
+}
+
 export function useI18n() {
   const ctx = useWidgetContextOrThrow("useI18n");
   const i18n = ctx.i18n || {};

package/dist/index.d.ts

@@ -28,6 +28,9 @@ export type WidgetPropertyType =
   | "tableRef"
   | "columnRef"
   | "recordBinding"
+  // REQ-USERMGMT M4 / §4.8: Group picker that emits a bare
+  // AppUserGroup UUID into the page JSON.
+  | "groupRef"
   | "expression"
   | "eventBinding"
   | "object"
@@ -480,6 +483,109 @@ export class DatastoreError extends Error {
   );
 }
 
+/**
+ * REQ-USERMGMT / REQ-ACL-SYS M3 — error class thrown by `useUsers` and
+ * `useGroups` callbacks. The `code` is a stable categorisation widgets
+ * can branch on.
+ */
+export class DirectoryError extends Error {
+  code:
+    | "FORBIDDEN"
+    | "VALIDATION"
+    | "NOT_FOUND"
+    | "INVITE_ONLY"
+    | "INTERNAL";
+  constructor(
+    code: DirectoryError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
+// --------------------------------------------------------------- useUsers
+//
+// REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
+
+export interface AppUserRow {
+  id: string;
+  name: string;
+  email?: string;
+  role: "USER" | "INTEGRATION";
+  isActive: boolean;
+}
+
+export interface UsersQuery {
+  q?: string;
+  role?: "USER" | "INTEGRATION" | "ALL";
+  isActive?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface InviteArgs {
+  email: string;
+  name?: string;
+  groupIds?: string[];
+}
+
+export interface AppUserInviteRow {
+  id: string;
+  email: string;
+  status: string;
+  invitedAt?: string;
+  expiresAt?: string;
+}
+
+export interface UsersApi {
+  users: AppUserRow[];
+  loading: boolean;
+  error: DirectoryError | null;
+  refetch(): Promise<void>;
+  invite(args: InviteArgs): Promise<AppUserInviteRow>;
+  deactivate(userId: string): Promise<AppUserRow>;
+  reactivate(userId: string): Promise<AppUserRow>;
+  remove(userId: string): Promise<void>;
+}
+
+/**
+ * AppUser administration. Reads require the `users.read:*` scope in the
+ * manifest; mutations additionally require `users.write:*`. Widgets that
+ * declare the scopes but whose calling APP_USER lacks the corresponding
+ * SystemAcl `users.*` capability grant get a `FORBIDDEN` DirectoryError.
+ */
+export function useUsers(query?: UsersQuery): UsersApi;
+
+// --------------------------------------------------------------- useGroups
+
+export interface AppUserGroupRow {
+  id: string;
+  name: string;
+  memberCount?: number;
+}
+
+export interface GroupsQuery {
+  q?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface GroupsApi {
+  groups: AppUserGroupRow[];
+  loading: boolean;
+  error: DirectoryError | null;
+  refetch(): Promise<void>;
+  create(args: { name: string }): Promise<AppUserGroupRow>;
+  remove(groupId: string): Promise<void>;
+  addMember(groupId: string, userId: string): Promise<void>;
+  removeMember(groupId: string, userId: string): Promise<void>;
+}
+
+/**
+ * AppUserGroup administration. Reads require `groups.read:*`; mutations
+ * require `groups.write:*`. Same SystemAcl gating as `useUsers`.
+ */
+export function useGroups(query?: GroupsQuery): GroupsApi;
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;

package/dist/index.js

@@ -9,11 +9,14 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
   useFile,
   useDatastoreMutation,
   useDirectory,
+  useUsers,
+  useGroups,
   useWidgetEvent,
   usePayments,
   useTheme,

package/dist/index.native.js

@@ -9,11 +9,14 @@ export {
   WidgetContextProvider,
   DatastoreError,
   PaymentError,
+  DirectoryError,
   useDatastoreQuery,
   useDatastoreRecord,
   useFile,
   useDatastoreMutation,
   useDirectory,
+  useUsers,
+  useGroups,
   useWidgetEvent,
   usePayments,
   useTheme,

package/dist/linter.cjs

@@ -74,7 +74,101 @@ function bannedIdentifiers() {
   return CONTRACT.bannedApis.map((b) => b.identifier);
 }
 
-function lintSource(source) {
+// REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
+// linter.js for the rationale comment. The two files must stay in
+// lockstep (the contract test asserts behaviour-equivalence).
+const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate", "remove"];
+const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
+const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
+
+function _scopeRules(source, manifest) {
+  const findings = [];
+  if (!manifest || typeof manifest !== "object") return findings;
+  const declared = new Set(
+    Array.isArray(manifest.requestedScopes)
+      ? manifest.requestedScopes.filter((s) => typeof s === "string")
+      : [],
+  );
+  const usesUsersHook = /\buseUsers\s*\(/.test(source);
+  const usesGroupsHook = /\buseGroups\s*\(/.test(source);
+
+  if (usesUsersHook) {
+    const reads = declared.has("users.read:*") || declared.has("users.read");
+    if (!reads) {
+      findings.push({
+        rule: "scope-required-for-useUsers",
+        label:
+          "useUsers() requires `users.read:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
+  if (usesGroupsHook) {
+    const reads = declared.has("groups.read:*") || declared.has("groups.read");
+    if (!reads) {
+      findings.push({
+        rule: "scope-required-for-useGroups",
+        label:
+          "useGroups() requires `groups.read:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
+
+  const lines = source.split(/\r?\n/);
+  let firedUsersWrite = false;
+  let firedGroupsWrite = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (SKIP_COMMENT.test(line)) continue;
+    if (usesUsersHook && !firedUsersWrite) {
+      for (const m of USER_MUTATION_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          if (
+            !declared.has("users.write:*") &&
+            !declared.has("users.write")
+          ) {
+            findings.push({
+              rule: "scope-required-for-user-mutation",
+              label: `useUsers().${m}() requires \`users.write:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedUsersWrite = true;
+          break;
+        }
+      }
+    }
+    if (usesGroupsHook && !firedGroupsWrite) {
+      for (const m of GROUP_MUTATION_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          if (m === "remove" && usesUsersHook) continue;
+          if (
+            !declared.has("groups.write:*") &&
+            !declared.has("groups.write")
+          ) {
+            findings.push({
+              rule: "scope-required-for-group-mutation",
+              label: `useGroups().${m}() requires \`groups.write:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedGroupsWrite = true;
+          break;
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
       ok: false,
@@ -98,6 +192,7 @@ function lintSource(source) {
       }
     }
   }
+  findings.push(..._scopeRules(source, options && options.manifest));
   return { ok: findings.length === 0, findings };
 }
 

package/dist/linter.js

@@ -83,12 +83,127 @@ export function bannedIdentifiers() {
   return CONTRACT.bannedApis.map((b) => b.identifier);
 }
 
+// REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
+//
+// A widget that calls `useUsers().invite()` / `.deactivate()` /
+// `.reactivate()` / `.remove()` MUST declare `users.write:*` in its
+// manifest's `requestedScopes`; similarly `useGroups()` mutation methods
+// require `groups.write:*`. The rule is enforced statically so a manifest
+// that drifts from the source (e.g. an author forgot to add the scope
+// after wiring up the mutation) is rejected at submission time.
+//
+// The check is pattern-based: scan the source for `.invite(`, `.deactivate(`
+// etc. and only fire when the source ALSO contains `useUsers(` / `useGroups(`
+// nearby (i.e. the destructured callee likely originated from the hook).
+// False positives are accepted in exchange for keeping the linter
+// AST-free; an author whose code happened to spell `.invite(` for an
+// unrelated reason can opt out with a `// @appstudio-skip-scope-check`
+// trailing comment on the offending line.
+const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate", "remove"];
+const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
+const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
+
+function _scopeRules(source, manifest) {
+  const findings = [];
+  if (!manifest || typeof manifest !== "object") return findings;
+  const declared = new Set(
+    Array.isArray(manifest.requestedScopes)
+      ? manifest.requestedScopes.filter((s) => typeof s === "string")
+      : [],
+  );
+  const usesUsersHook = /\buseUsers\s*\(/.test(source);
+  const usesGroupsHook = /\buseGroups\s*\(/.test(source);
+
+  if (usesUsersHook) {
+    const reads = declared.has("users.read:*") || declared.has("users.read");
+    if (!reads) {
+      findings.push({
+        rule: "scope-required-for-useUsers",
+        label:
+          "useUsers() requires `users.read:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
+  if (usesGroupsHook) {
+    const reads = declared.has("groups.read:*") || declared.has("groups.read");
+    if (!reads) {
+      findings.push({
+        rule: "scope-required-for-useGroups",
+        label:
+          "useGroups() requires `groups.read:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
+
+  const lines = source.split(/\r?\n/);
+  let firedUsersWrite = false;
+  let firedGroupsWrite = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (SKIP_COMMENT.test(line)) continue;
+    if (usesUsersHook && !firedUsersWrite) {
+      for (const m of USER_MUTATION_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          if (
+            !declared.has("users.write:*") &&
+            !declared.has("users.write")
+          ) {
+            findings.push({
+              rule: "scope-required-for-user-mutation",
+              label: `useUsers().${m}() requires \`users.write:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedUsersWrite = true;
+          break;
+        }
+      }
+    }
+    if (usesGroupsHook && !firedGroupsWrite) {
+      for (const m of GROUP_MUTATION_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          // `.remove(` is also a useUsers method; only blame groups
+          // when the source also uses the groups hook AND the source
+          // doesn't ALSO use the users hook (an ambiguous .remove(
+          // is best left to the user-mutation rule above).
+          if (m === "remove" && usesUsersHook) continue;
+          if (
+            !declared.has("groups.write:*") &&
+            !declared.has("groups.write")
+          ) {
+            findings.push({
+              rule: "scope-required-for-group-mutation",
+              label: `useGroups().${m}() requires \`groups.write:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedGroupsWrite = true;
+          break;
+        }
+      }
+    }
+  }
+  return findings;
+}
+
 /**
  * Lint a JavaScript source string.
+ *
  * @param {string} source
+ * @param {{ manifest?: { requestedScopes?: string[] } }} [options] — when a
+ *   manifest is supplied, scope-aware rules also fire (see
+ *   `scope-required-for-user-mutation`).
  * @returns {{ ok: boolean, findings: Array<{ rule: string, label: string, line: number, snippet: string }> }}
  */
-export function lintSource(source) {
+export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
       ok: false,
@@ -112,5 +227,9 @@ export function lintSource(source) {
       }
     }
   }
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
+  // line-by-line scan so banned-identifier findings stay first in the
+  // output.
+  findings.push(..._scopeRules(source, options && options.manifest));
   return { ok: findings.length === 0, findings };
 }

package/dist/property-schema.js

@@ -6,6 +6,12 @@ const VALID_TYPES = new Set([
   "color", "icon", "image",
   "select", "multiselect",
   "tableRef", "columnRef", "recordBinding",
+  // REQ-USERMGMT M4 / §4.8: `groupRef` is a Group picker that emits a bare
+  // AppUserGroup UUID into the page JSON. Renders via `GroupSelector` in
+  // the Studio Properties Panel. REQ-GEN-07 compliance: no typed UUIDs —
+  // value is the raw uuid string so the tenant-copy walker can remap it
+  // through `_remapJson` without per-prop hooks.
+  "groupRef",
   "expression", "eventBinding",
   "object", "array",
 ]);
@@ -87,6 +93,7 @@ function coerceLeaf(def, value, path, errors) {
     case "tableRef":
     case "columnRef":
     case "recordBinding":
+    case "groupRef":
     case "expression":
     case "eventBinding":
       if (typeof value !== "string") errors.push(`${path}: expected string`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/linter-users-scope.test.js"
   },
   "engines": {
     "node": ">=18"