@colixsystems/widget-sdk 0.33.0 → 0.35.0

package/README.md

@@ -11,7 +11,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | `ctx.files` | `@colixsystems/files-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useFile()` resolves |
 | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
 
-**Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no client-side case transform anywhere** — the only transform left in the system is the backend's wire ↔ Prisma middleware. Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
+**Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
 **Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (18 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
 
@@ -36,6 +36,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (mutations also `users.write:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
+| **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
@@ -46,7 +47,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.33.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.35.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.35.0
+
+**Folder-ACL + signer-roster hooks (REQ-FSH / REQ-SIGN).** Two admin/MANAGE-gated hooks reading the existing `ctx.filestore`:
+- `useFileRoster(fileId, { limit?, offset?, enabled? })` → `{ roster, total, signedCount, loading, error, refetch }` — the signer roster for one file: the folder audience (every member of an open project folder, or the granted users/groups of a restricted one), each annotated `signed` with `signer_name` / `signed_at`. Reads `ctx.filestore.signatures.roster` (new `@colixsystems/filestore-client` **0.5.0** method); the host 403s a non-manager, so use `error` to hide the panel for non-admins.
+- `useFolderPermissions(folderId, { enabled? })` → `{ grants, loading, busy, error, refetch, grant, revoke, setVisibility }` — manage a folder's permissions (the Filestore ACL): `grant(subjectType, subjectId, 'VIEW'|'DOWNLOAD'|'MANAGE')`, `revoke(shareId)`, `setVisibility('INHERIT'|'RESTRICTED')`. Pair the user/group picker with `useUsers` / `useGroups`.
+
+Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own signatures only) — the backend tightened; the hook's shape is unchanged. **`CONTRACT.version` → `1.25.0`** (additive: two new hooks; the underlying `filestore-client` → `0.5.0`, shares folder-scoped).
+
+### What's new in 0.34.0
+
+**`useBankIdLink()` — link / unlink BankID from a widget (REQ-BANKID-AUTH).** A new DIRECTORY hook reading the new `ctx.directory.bankid` namespace on `@colixsystems/directory-client` **0.2.0** (`status` / `startLink` / `collect` / `cancel` / `unlink`). It lets a signed-in app-user attach a BankID identity to their account (or remove it) via an animated-QR poll — `startLink()` opens the order, `refresh()` polls it (drive on a ~2s interval while `status === "pending"`; render `qr` with the `Image` primitive), `unlink()` removes it. `available` is `false` when BankID can't be used in the app (provider disabled or no platform cert) — hide the affordance then. Self-service + JWT-gated, so **no `requestedScopes` entry is required**. Backs the built-in **User** widget's "Link BankID" section. `CONTRACT.version` → `1.24.0`. Additive — no existing export or type changed.
 
 ### What's new in 0.33.0
 

package/dist/contract.cjs

@@ -236,6 +236,51 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFileRoster",
+    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    description:
+      "MANAGE-gated signer roster for one Filestore file: the people expected " +
+      "to be able to sign it (the file's folder audience) each annotated " +
+      "signed/not-signed, plus a distinct signed_count. Reads " +
+      "ctx.filestore.signatures.roster and unwraps { data, meta }. The host 403s " +
+      "a caller who can see the file but does not MANAGE its folder — surface " +
+      "that as 'not an admin here' via `error`.",
+    returnShape: {
+      roster:
+        "{ app_user_id, name, signed, signature_id, signer_name, signed_at }[]",
+      total: "number",
+      signedCount: "number",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFolderPermissions",
+    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    description:
+      "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
+      "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
+      "/ revoke(shareId) / setVisibility('INHERIT' | 'RESTRICTED') — all MANAGE " +
+      "actions the host enforces. Reads ctx.filestore.shares + ctx.filestore." +
+      "folders; pair the user/group picker with useUsers / useGroups.",
+    returnShape: {
+      grants:
+        "{ id, folder_id, subject_type, subject_id, permission, created_at }[]",
+      loading: "boolean",
+      busy: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+      grant: "(subjectType, subjectId, permission) => Promise<share>",
+      revoke: "(shareId) => Promise<void>",
+      setVisibility: "(visibility) => Promise<folder>",
+    },
+    requiredContextSlice: ["filestore.shares", "filestore.folders"],
+    scopes: ["files.read:*", "files.write:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -377,6 +422,42 @@ const HOOKS = [
     requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in
+  // app-user. Self-service + JWT-gated (no widget scope). Mirror of contract.js.
+  {
+    name: "useBankIdLink",
+    signature: "useBankIdLink()",
+    description:
+      "Link / unlink a BankID identity to the signed-in app-user via the " +
+      "injected directory-client at ctx.directory.bankid.{status,startLink," +
+      "collect,cancel,unlink}. Returns { linked, available, status, qr, message, " +
+      "loading, statusLoading, error, startLink, refresh, cancel, unlink, " +
+      "refetchStatus }. On mount it reads the link status; `available` is false " +
+      "when BankID can't be used here (provider disabled or no platform cert) — " +
+      "hide the Link affordance then. The link flow is an animated-QR poll like " +
+      "useFileSignature: startLink() opens an order (status 'pending' + qr — a " +
+      "PNG data-URL, render with the Image primitive); refresh() polls (drive on " +
+      "a ~2s interval while pending; sets linked=true on complete); cancel() " +
+      "aborts; unlink() removes the link (rejects DirectoryError LAST_AUTH_METHOD " +
+      "when BankID is the only sign-in method). No requestedScopes entry needed.",
+    returnShape: {
+      linked: "boolean | null  // null until the status loads",
+      available: "boolean  // false → hide the Link affordance",
+      status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR",
+      message: "string | null",
+      loading: "boolean",
+      statusLoading: "boolean",
+      error: "DirectoryError | null",
+      startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      unlink: "() => Promise<{ linked: boolean }>  // rejects with DirectoryError",
+      refetchStatus: "() => Promise<{ linked, available }>",
+    },
+    requiredContextSlice: ["directory.bankid"],
+    scopes: null,
+  },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
   // management for a single record. Mirror of contract.js.
   {
@@ -809,10 +890,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/directory-client instance. " +
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
-      "invites: { list(), revoke(id), resend(id) } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "invites: { list(), revoke(id), resend(id) }, " +
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { users: "object", groups: "object" },
+    fields: { users: "object", groups: "object", bankid: "object" },
   },
   files: {
     description:
@@ -830,7 +912,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
       "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
   renderer: {
     description:
@@ -1349,7 +1431,23 @@ const CONTRACT = deepFreeze({
   //    form-root tableId switches) and `ui.defaultFactory: "tabId"`
   //    (per-instance dynamic default). No existing field, hook, primitive,
   //    or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.23.0",
+  //
+  // 1.24.0: additive (REQ-BANKID-AUTH) — new `useBankIdLink()` hook reading the
+  //    new `ctx.directory.bankid` namespace (status/startLink/collect/cancel/
+  //    unlink) on the @colixsystems/directory-client (0.2.0). Lets the built-in
+  //    User widget link / unlink a BankID identity to the signed-in app-user
+  //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
+  //    No existing hook, primitive, or field changed shape — minor bump on the
+  //    pre-1.0 channel.
+  //
+  // 1.25.0: additive (REQ-FSH / REQ-SIGN) — new `useFileRoster(fileId)`
+  //    (MANAGE-gated signer roster: the folder audience annotated
+  //    signed/not-signed) and `useFolderPermissions(folderId)` (manage the
+  //    folder ACL: list grants + grant/revoke a VIEW/DOWNLOAD/MANAGE tier +
+  //    setVisibility). Both read the existing `ctx.filestore`; the underlying
+  //    `filestore-client` 0.5.0 made shares folder-scoped + added
+  //    `signatures.roster`. No existing hook changed.
+  version: "1.25.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -236,6 +236,51 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFileRoster",
+    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    description:
+      "MANAGE-gated signer roster for one Filestore file: the people expected " +
+      "to be able to sign it (the file's folder audience) each annotated " +
+      "signed/not-signed, plus a distinct signed_count. Reads " +
+      "ctx.filestore.signatures.roster and unwraps { data, meta }. The host 403s " +
+      "a caller who can see the file but does not MANAGE its folder — surface " +
+      "that as 'not an admin here' via `error`.",
+    returnShape: {
+      roster:
+        "{ app_user_id, name, signed, signature_id, signer_name, signed_at }[]",
+      total: "number",
+      signedCount: "number",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFolderPermissions",
+    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    description:
+      "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
+      "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
+      "/ revoke(shareId) / setVisibility('INHERIT' | 'RESTRICTED') — all MANAGE " +
+      "actions the host enforces. Reads ctx.filestore.shares + ctx.filestore." +
+      "folders; pair the user/group picker with useUsers / useGroups.",
+    returnShape: {
+      grants:
+        "{ id, folder_id, subject_type, subject_id, permission, created_at }[]",
+      loading: "boolean",
+      busy: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+      grant: "(subjectType, subjectId, permission) => Promise<share>",
+      revoke: "(shareId) => Promise<void>",
+      setVisibility: "(visibility) => Promise<folder>",
+    },
+    requiredContextSlice: ["filestore.shares", "filestore.folders"],
+    scopes: ["files.read:*", "files.write:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -377,6 +422,42 @@ const HOOKS = [
     requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in
+  // app-user. Self-service + JWT-gated (no widget scope). Mirror of contract.cjs.
+  {
+    name: "useBankIdLink",
+    signature: "useBankIdLink()",
+    description:
+      "Link / unlink a BankID identity to the signed-in app-user via the " +
+      "injected directory-client at ctx.directory.bankid.{status,startLink," +
+      "collect,cancel,unlink}. Returns { linked, available, status, qr, message, " +
+      "loading, statusLoading, error, startLink, refresh, cancel, unlink, " +
+      "refetchStatus }. On mount it reads the link status; `available` is false " +
+      "when BankID can't be used here (provider disabled or no platform cert) — " +
+      "hide the Link affordance then. The link flow is an animated-QR poll like " +
+      "useFileSignature: startLink() opens an order (status 'pending' + qr — a " +
+      "PNG data-URL, render with the Image primitive); refresh() polls (drive on " +
+      "a ~2s interval while pending; sets linked=true on complete); cancel() " +
+      "aborts; unlink() removes the link (rejects DirectoryError LAST_AUTH_METHOD " +
+      "when BankID is the only sign-in method). No requestedScopes entry needed.",
+    returnShape: {
+      linked: "boolean | null  // null until the status loads",
+      available: "boolean  // false → hide the Link affordance",
+      status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR",
+      message: "string | null",
+      loading: "boolean",
+      statusLoading: "boolean",
+      error: "DirectoryError | null",
+      startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      unlink: "() => Promise<{ linked: boolean }>  // rejects with DirectoryError",
+      refetchStatus: "() => Promise<{ linked, available }>",
+    },
+    requiredContextSlice: ["directory.bankid"],
+    scopes: null,
+  },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
   // management for a single record. Mirror of contract.js.
   {
@@ -809,10 +890,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/directory-client instance. " +
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
-      "invites: { list(), revoke(id), resend(id) } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "invites: { list(), revoke(id), resend(id) }, " +
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { users: "object", groups: "object" },
+    fields: { users: "object", groups: "object", bankid: "object" },
   },
   files: {
     description:
@@ -830,7 +912,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
       "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
   renderer: {
     description:
@@ -1349,7 +1431,23 @@ const CONTRACT = deepFreeze({
   //    form-root tableId switches) and `ui.defaultFactory: "tabId"`
   //    (per-instance dynamic default). No existing field, hook, primitive,
   //    or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.23.0",
+  //
+  // 1.24.0: additive (REQ-BANKID-AUTH) — new `useBankIdLink()` hook reading the
+  //    new `ctx.directory.bankid` namespace (status/startLink/collect/cancel/
+  //    unlink) on the @colixsystems/directory-client (0.2.0). Lets the built-in
+  //    User widget link / unlink a BankID identity to the signed-in app-user
+  //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
+  //    No existing hook, primitive, or field changed shape — minor bump on the
+  //    pre-1.0 channel.
+  //
+  // 1.25.0: additive (REQ-FSH / REQ-SIGN) — new `useFileRoster(fileId)`
+  //    (MANAGE-gated signer roster: the folder audience annotated
+  //    signed/not-signed) and `useFolderPermissions(folderId)` (manage the
+  //    folder ACL: list grants + grant/revoke a VIEW/DOWNLOAD/MANAGE tier +
+  //    setVisibility). Both read the existing `ctx.filestore`; the underlying
+  //    `filestore-client` 0.5.0 made shares folder-scoped + added
+  //    `signatures.roster`. No existing hook changed.
+  version: "1.25.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -1503,6 +1503,193 @@ export function useFileSignatures(fileIds) {
   return { signaturesByFileId, loading, error, refetch };
 }
 
+/**
+ * REQ-SIGN: MANAGE-gated signer roster for one file — the people expected to be
+ * able to sign it (the file's folder audience) each annotated signed/not-signed.
+ * Reads ctx.filestore.signatures.roster. The host backend 403s a caller who can
+ * see the file but doesn't manage its folder, so `error` (a ForbiddenError) is
+ * the "you're not an admin here" signal the widget hides on. Returns
+ * { roster, total, signedCount, loading, error, refetch }. `roster` items are
+ * { app_user_id, name, signed, signature_id, signer_name, signed_at }.
+ */
+export function useFileRoster(fileId, options = {}) {
+  const ctx = useWidgetContextOrThrow("useFileRoster");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.signatures ||
+    typeof ctx.filestore.signatures.roster !== "function"
+  ) {
+    throw new Error(
+      "useFileRoster: host did not inject a filestore client (ctx.filestore.signatures.roster)",
+    );
+  }
+  const { limit = 50, offset = 0, enabled = true } = options;
+  const [roster, setRoster] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [signedCount, setSignedCount] = useState(0);
+  const [loading, setLoading] = useState(Boolean(fileId) && enabled);
+  const [error, setError] = useState(null);
+
+  const sigRef = useRef(ctx.filestore.signatures);
+  sigRef.current = ctx.filestore.signatures;
+  const argsRef = useRef({ fileId, limit, offset, enabled });
+  argsRef.current = { fileId, limit, offset, enabled };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { fileId: fid, limit: lim, offset: off, enabled: en } = argsRef.current;
+    if (!fid || !en) {
+      setLoading(false);
+      setError(null);
+      setRoster([]);
+      setTotal(0);
+      setSignedCount(0);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await sigRef.current.roster(fid, { limit: lim, offset: off });
+      if (runRef.current !== myRun) return;
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      const meta = (res && res.meta) || {};
+      setRoster(rows);
+      setTotal(typeof meta.total === "number" ? meta.total : rows.length);
+      setSignedCount(typeof meta.signed_count === "number" ? meta.signed_count : 0);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId, limit, offset, enabled]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { roster, total, signedCount, loading, error, refetch };
+}
+
+/**
+ * REQ-FSH: folder-permission management for one folder (the Filestore ACL).
+ * Reads ctx.filestore.shares + ctx.filestore.folders. Lists the folder's grants
+ * and exposes grant / revoke / setVisibility mutations — all MANAGE actions the
+ * host backend enforces (a non-manager's mutation rejects). Pair the user/group
+ * picker with useUsers / useGroups. Returns { grants, loading, busy, error,
+ * refetch, grant, revoke, setVisibility }.
+ */
+export function useFolderPermissions(folderId, options = {}) {
+  const ctx = useWidgetContextOrThrow("useFolderPermissions");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.shares ||
+    typeof ctx.filestore.shares.list !== "function" ||
+    !ctx.filestore.folders ||
+    typeof ctx.filestore.folders.update !== "function"
+  ) {
+    throw new Error(
+      "useFolderPermissions: host did not inject a filestore client (ctx.filestore.shares / ctx.filestore.folders)",
+    );
+  }
+  const { enabled = true } = options;
+  const [grants, setGrants] = useState([]);
+  const [loading, setLoading] = useState(Boolean(folderId) && enabled);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+
+  const sharesRef = useRef(ctx.filestore.shares);
+  sharesRef.current = ctx.filestore.shares;
+  const foldersRef = useRef(ctx.filestore.folders);
+  foldersRef.current = ctx.filestore.folders;
+  const idRef = useRef({ folderId, enabled });
+  idRef.current = { folderId, enabled };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { folderId: fid, enabled: en } = idRef.current;
+    if (!fid || !en) {
+      setLoading(false);
+      setError(null);
+      setGrants([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await sharesRef.current.list({ folder_id: fid });
+      if (runRef.current !== myRun) return;
+      setGrants(res && Array.isArray(res.data) ? res.data : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [folderId, enabled]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const grant = useCallback(
+    async (subjectType, subjectId, permission) => {
+      const { folderId: fid } = idRef.current;
+      setBusy(true);
+      try {
+        const row = await sharesRef.current.create({
+          folder_id: fid,
+          subject_type: subjectType,
+          subject_id: subjectId,
+          permission,
+        });
+        await doFetch();
+        return row;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [doFetch],
+  );
+
+  const revoke = useCallback(
+    async (shareId) => {
+      setBusy(true);
+      try {
+        await sharesRef.current.remove(shareId);
+        await doFetch();
+      } finally {
+        setBusy(false);
+      }
+    },
+    [doFetch],
+  );
+
+  const setVisibility = useCallback(async (visibility) => {
+    const { folderId: fid } = idRef.current;
+    setBusy(true);
+    try {
+      return await foldersRef.current.update(fid, { visibility });
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  return { grants, loading, busy, error, refetch, grant, revoke, setVisibility };
+}
+
 /* ============================================================================
  * DIRECTORY CLIENT — ctx.directory (@colixsystems/directory-client)
  *
@@ -1850,6 +2037,170 @@ export function useGroups(query) {
   return { groups, loading, error, refetch, create, remove, addMember, removeMember };
 }
 
+/**
+ * REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in app-user,
+ * and read whether BankID is available + already linked. Returns
+ * `{ linked, available, status, qr, message, loading, statusLoading, error,
+ * startLink, refresh, cancel, unlink, refetchStatus }`.
+ *
+ * Reads the injected `@colixsystems/directory-client` at `ctx.directory.bankid`
+ * (a self-service, JWT-gated surface — no widget scope needed). On mount it
+ * fetches the link status; `available` is false when BankID can't be used in
+ * this app (provider disabled or no platform cert), so a widget should hide the
+ * Link affordance entirely when `!available`.
+ *
+ * The link flow is an animated-QR poll, mirroring `useFileSignature`:
+ *   - `startLink()` opens an order → sets `status: "pending"` + `qr` (a PNG
+ *     data-URL; render it with the `Image` primitive).
+ *   - `refresh()` polls the order — refreshing the QR frame while pending and,
+ *     on completion, setting `linked: true` + `status: "complete"`. The widget
+ *     drives the cadence (e.g. a 2s interval while `status === "pending"`).
+ *   - `cancel()` aborts the in-flight order.
+ *   - `unlink()` removes the link (rejects with a DirectoryError carrying
+ *     `code: "LAST_AUTH_METHOD"` / status 409 when BankID is the user's only
+ *     sign-in method).
+ *
+ * No `requestedScopes` entry is required — the endpoints are gated by the
+ * app-user session the host already holds.
+ */
+export function useBankIdLink() {
+  const ctx = useWidgetContextOrThrow("useBankIdLink");
+  if (
+    !ctx.directory ||
+    !ctx.directory.bankid ||
+    typeof ctx.directory.bankid.status !== "function"
+  ) {
+    throw new Error(
+      "useBankIdLink: host did not inject a directory client (ctx.directory.bankid)",
+    );
+  }
+  // `ctx` is a fresh identity each host render — hold the namespace in a ref so
+  // the callbacks stay stable.
+  const apiRef = useRef(ctx.directory.bankid);
+  apiRef.current = ctx.directory.bankid;
+
+  const [linked, setLinked] = useState(null); // null until the status loads
+  const [available, setAvailable] = useState(false);
+  const [statusLoading, setStatusLoading] = useState(true);
+  const [status, setStatus] = useState(null); // null | pending | complete | failed | cancelled
+  const [qr, setQr] = useState(null);
+  const [message, setMessage] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const orderRef = useRef(null);
+
+  const refetchStatus = useCallback(async () => {
+    setStatusLoading(true);
+    try {
+      const res = await apiRef.current.status();
+      setLinked(Boolean(res && res.linked));
+      setAvailable(Boolean(res && res.available));
+      setStatusLoading(false);
+      return res;
+    } catch (err) {
+      setError(toDirectoryError(err));
+      setStatusLoading(false);
+      return null;
+    }
+  }, []);
+
+  useEffect(() => {
+    refetchStatus();
+  }, [refetchStatus]);
+
+  const startLink = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await apiRef.current.startLink();
+      orderRef.current = res && res.order_ref ? res.order_ref : null;
+      setStatus(res && res.status ? res.status : "pending");
+      setQr(res && res.qr ? res.qr : null);
+      setMessage(null);
+      setLoading(false);
+      return res;
+    } catch (err) {
+      const e = toDirectoryError(err);
+      setError(e);
+      setStatus("failed");
+      setMessage(e.message);
+      setLoading(false);
+      throw e;
+    }
+  }, []);
+
+  const refresh = useCallback(async () => {
+    const id = orderRef.current;
+    if (!id) return null;
+    try {
+      const res = await apiRef.current.collect(id);
+      if (res) {
+        if (res.status != null) setStatus(res.status);
+        if (res.qr !== undefined) setQr(res.qr || null);
+        if (res.message !== undefined) setMessage(res.message || null);
+        if (res.status === "complete") setLinked(true);
+      }
+      return res;
+    } catch (err) {
+      // A terminal client error (e.g. 409 BANKID_ALREADY_LINKED) carries a
+      // helpful message — surface it as a failed order rather than throwing
+      // into the widget's poll interval.
+      const e = toDirectoryError(err);
+      setError(e);
+      setStatus("failed");
+      setMessage(e.message);
+      return null;
+    }
+  }, []);
+
+  const cancel = useCallback(async () => {
+    const id = orderRef.current;
+    orderRef.current = null;
+    setStatus(null);
+    setQr(null);
+    setMessage(null);
+    if (id) {
+      try {
+        await apiRef.current.cancel(id);
+      } catch {
+        // best-effort — the order may have already expired.
+      }
+    }
+  }, []);
+
+  const unlink = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await apiRef.current.unlink();
+      setLinked(Boolean(res && res.linked));
+      setLoading(false);
+      return res;
+    } catch (err) {
+      const e = toDirectoryError(err);
+      setError(e);
+      setLoading(false);
+      throw e;
+    }
+  }, []);
+
+  return {
+    linked,
+    available,
+    status,
+    qr,
+    message,
+    loading,
+    statusLoading,
+    error,
+    startLink,
+    refresh,
+    cancel,
+    unlink,
+    refetchStatus,
+  };
+}
+
 /* ============================================================================
  * PAYMENTS CLIENT — ctx.payments (@colixsystems/payments-client)
  *

package/dist/index.d.ts

@@ -354,6 +354,24 @@ export interface DirectoryClient {
     revoke(inviteId: string): Promise<void>;
     resend(inviteId: string): Promise<unknown>;
   };
+  /** REQ-BANKID-AUTH — backs `useBankIdLink`. */
+  bankid: {
+    status(): Promise<{ linked: boolean; available: boolean }>;
+    startLink(): Promise<{
+      order_ref: string;
+      auto_start_token: string | null;
+      qr: string | null;
+      status: "pending";
+    }>;
+    collect(orderRef: string): Promise<{
+      status: "pending" | "complete" | "failed" | "cancelled";
+      qr?: string | null;
+      message?: string;
+      linked?: boolean;
+    }>;
+    cancel(orderRef: string): Promise<{ status: "cancelled" }>;
+    unlink(): Promise<{ linked: boolean }>;
+  };
 }
 
 /**
@@ -924,6 +942,45 @@ export interface GroupsApi {
  */
 export function useGroups(query?: GroupsQuery): GroupsApi;
 
+// ----------------------------------------------------- useBankIdLink
+//
+// REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in app-user.
+// Reads the injected directory-client at `ctx.directory.bankid`. Self-service,
+// JWT-gated — no requestedScopes entry needed.
+
+export interface BankIdLinkApi {
+  /** Whether the user currently has BankID linked (null until the status loads). */
+  linked: boolean | null;
+  /** Whether BankID linking can be used in this app (provider enabled + platform cert). */
+  available: boolean;
+  /** The active link order's state, or null when no order is in flight. */
+  status: "pending" | "complete" | "failed" | "cancelled" | null;
+  /** PNG data-URL of the animated BankID QR while pending (render with the Image primitive). */
+  qr: string | null;
+  message: string | null;
+  loading: boolean;
+  statusLoading: boolean;
+  error: DirectoryError | null;
+  /** Open a link order → sets status "pending" + qr. */
+  startLink(): Promise<unknown>;
+  /** Poll the open order; on completion sets linked=true. Drive on an interval while pending. */
+  refresh(): Promise<unknown>;
+  /** Abort the in-flight order. */
+  cancel(): Promise<void>;
+  /** Remove the link (rejects with DirectoryError code LAST_AUTH_METHOD when it is the only method). */
+  unlink(): Promise<{ linked: boolean }>;
+  /** Re-read { linked, available }. */
+  refetchStatus(): Promise<unknown>;
+}
+
+/**
+ * Link / unlink a BankID identity to the signed-in app-user and read the
+ * current link + availability state. Reads `ctx.directory.bankid`. No
+ * requestedScopes entry is required — the endpoints are gated by the app-user
+ * session the host holds. Hide the Link affordance when `available` is false.
+ */
+export function useBankIdLink(): BankIdLinkApi;
+
 // ----------------------------------------------------- useRecordPermissions
 //
 // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission

package/dist/index.js

@@ -19,10 +19,13 @@ export {
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
+  useFileRoster,
+  useFolderPermissions,
   useDatastoreMutation,
   useDirectory,
   useUsers,
   useGroups,
+  useBankIdLink,
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,

package/dist/index.native.js

@@ -23,6 +23,7 @@ export {
   useDirectory,
   useUsers,
   useGroups,
+  useBankIdLink,
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",