@colixsystems/widget-sdk 0.218.0 → 0.219.1

package/dist/signing-hooks.js

@@ -0,0 +1,449 @@
+// Signing a file with BankID, and signing rounds. One source for both entries:
+// index.js and index.native.js re-export the same three hooks. What a server
+// answer does to the state lives in ./signing-state.js, which needs no React.
+//
+// Every hook here answers for one SCOPE: the signed-in user plus the file (or
+// the set of files). State is stored with the scope it was read for and shown
+// only while that is still the scope, so one file's or one user's answer is
+// never rendered under another, not even for a single render.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { PermissionError, toPermissionError, useWidgetContextOrThrow } from "./hooks.js";
+import {
+  NO_SIGN_ORDER,
+  chunkFileIds,
+  currentRoundOrNull,
+  indexOverview,
+  readRefusalDetail,
+  reportedRoundId,
+  roundChangedUnderneath,
+  signOrderStateAfterAnswer,
+  signOrderStateAfterCancel,
+  signOrderStateAfterInitiate,
+  signedOrderState,
+  uniqueFileIds,
+} from "./signing-state.js";
+
+const userIdOf = (ctx) => (ctx.user && ctx.user.id) || "";
+
+/**
+ * Drive a BankID signing flow for one Filestore file. Returns
+ * `{ status, qr, autoStartToken, message, signerName, signedAt, hintCode,
+ * nameRefusal, verdict, loading, error, initiate, refresh, cancel, verify }`.
+ *
+ * `initiate()` opens a sign order against the file (the backend hashes its
+ * bytes SERVER-SIDE and binds the digest into the BankID signature); `refresh()`
+ * polls the order (surfacing a fresh animated-QR frame while pending — render
+ * it with the `Image` primitive); `verify()` re-runs the offline verification
+ * and returns the verdict (`{ valid, content_status, … }`). `cancel()` aborts
+ * the order and resolves to what became of it, which is not always
+ * "cancelled": a signature already being added to the document stays pending
+ * with `hintCode: "sealing"`. `hintCode` is where the order stands;
+ * `nameRefusal` (`{ reason, characters }`) is set when it failed because the
+ * signer's name cannot be shown. `autoStartToken` is set only while opening
+ * BankID can still help. Reads
+ * `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When `fileId` is
+ * null/empty the hook collapses to a no-op.
+ *
+ * Pass `existingSignatureId` for a file that is ALREADY signed: the hook seeds
+ * that order id (status `complete`) so the widget can show the signed state and
+ * `verify()` it WITHOUT opening a new order — re-signing then requires an
+ * explicit `initiate()`.
+ */
+export function useFileSignature(fileId, existingSignatureId = null) {
+  const ctx = useWidgetContextOrThrow("useFileSignature");
+  if (!ctx.filestore || !ctx.filestore.signatures) {
+    throw new Error(
+      "useFileSignature: host did not inject a filestore client (ctx.filestore.signatures)",
+    );
+  }
+  const ready = Boolean(fileId);
+  const scope = `${userIdOf(ctx)}|${fileId || ""}`;
+  const sigRef = useRef(ctx.filestore.signatures);
+  sigRef.current = ctx.filestore.signatures;
+  const fileIdRef = useRef(fileId);
+  fileIdRef.current = fileId;
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+  // Seed the order from an already-completed signature so verify() works
+  // without initiating; initiate() (an explicit re-sign) overwrites it.
+  const orderRef = useRef({ scope, id: existingSignatureId || null });
+  // Bumped whenever an older poll's answer must no longer be applied.
+  const answersRef = useRef(0);
+
+  const seeded = () => ({
+    scope,
+    order: existingSignatureId ? signedOrderState() : NO_SIGN_ORDER,
+    verdict: null,
+    error: null,
+  });
+  const [held, setHeld] = useState(seeded);
+  const [loadingScope, setLoadingScope] = useState(null);
+  // Another file or another user: the order that was open is not theirs.
+  const current = held.scope === scope ? held : seeded();
+  const currentRef = useRef(current);
+  currentRef.current = current;
+  if (orderRef.current.scope !== scope) {
+    orderRef.current = { scope, id: existingSignatureId || null };
+    answersRef.current += 1;
+  }
+
+  /** Apply `change` to the held state, unless the hook has moved to another scope. */
+  const apply = useCallback((forScope, change) => {
+    if (scopeRef.current !== forScope) return;
+    setHeld((previous) => {
+      const base = previous.scope === forScope ? previous : currentRef.current;
+      return { ...base, ...change(base) };
+    });
+  }, []);
+
+  const initiate = useCallback(async () => {
+    const forScope = scopeRef.current;
+    if (!fileIdRef.current) return null;
+    answersRef.current += 1;
+    setLoadingScope(forScope);
+    apply(forScope, () => ({ error: null, verdict: null }));
+    try {
+      const res = await sigRef.current.initiate(fileIdRef.current);
+      if (scopeRef.current === forScope) {
+        orderRef.current = { scope: forScope, id: res && res.signature_id ? res.signature_id : null };
+        answersRef.current += 1;
+      }
+      apply(forScope, () => ({ order: signOrderStateAfterInitiate(res) }));
+      return res;
+    } catch (err) {
+      const refusal = toPermissionError(err);
+      apply(forScope, () => ({ error: refusal }));
+      throw refusal;
+    } finally {
+      setLoadingScope((loadingFor) => (loadingFor === forScope ? null : loadingFor));
+    }
+  }, [apply]);
+
+  const refresh = useCallback(async () => {
+    const forScope = scopeRef.current;
+    const { id } = orderRef.current;
+    if (!id) return;
+    const asked = answersRef.current;
+    try {
+      const res = await sigRef.current.status(id);
+      // A cancel or a new order since this poll was sent: its answer is old news.
+      if (answersRef.current !== asked) return;
+      apply(forScope, (base) => ({ order: signOrderStateAfterAnswer(base.order, res) }));
+    } catch (err) {
+      if (answersRef.current !== asked) return;
+      apply(forScope, () => ({ error: toPermissionError(err) }));
+    }
+  }, [apply]);
+
+  const cancel = useCallback(async () => {
+    const forScope = scopeRef.current;
+    const { id } = orderRef.current;
+    if (!id) return undefined;
+    answersRef.current += 1;
+    try {
+      const res = await sigRef.current.cancel(id);
+      answersRef.current += 1;
+      apply(forScope, (base) => ({ order: signOrderStateAfterCancel(base.order, res) }));
+      return res;
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, [apply]);
+
+  const verify = useCallback(async () => {
+    const forScope = scopeRef.current;
+    const { id } = orderRef.current;
+    if (!id) return null;
+    try {
+      const v = await sigRef.current.verify(id);
+      apply(forScope, () => ({ verdict: v }));
+      return v;
+    } catch (err) {
+      const refusal = toPermissionError(err);
+      apply(forScope, () => ({ error: refusal }));
+      throw refusal;
+    }
+  }, [apply]);
+
+  if (!ready) {
+    return {
+      ...NO_SIGN_ORDER,
+      verdict: null,
+      loading: false,
+      error: null,
+      initiate: async () => null,
+      refresh: async () => undefined,
+      cancel: async () => undefined,
+      verify: async () => null,
+    };
+  }
+  return {
+    ...current.order,
+    verdict: current.verdict,
+    loading: loadingScope === scope,
+    error: current.error,
+    initiate,
+    refresh,
+    cancel,
+    verify,
+  };
+}
+
+/** A refusal with the server's code and message, the refused signers and the wait. */
+function toSigningRoundError(err) {
+  const error = toPermissionError(err);
+  if (error.errors === undefined) Object.assign(error, readRefusalDetail(err));
+  return error;
+}
+
+/** A refusal the hook makes itself; `message` is written to be shown to a person. */
+const localRefusal = (code, message) =>
+  Object.assign(new PermissionError(code, message, { retryable: false }), { errors: [], retryAfter: null });
+
+const noRound = () => localRefusal("NO_SIGNING_ROUND", "This document has no signing round.");
+const previewRequired = () =>
+  localRefusal("PREVIEW_REQUIRED", "Open the prepared document before sending it for signing.");
+const actionInProgress = () =>
+  localRefusal("ACTION_IN_PROGRESS", "Another change to this signing round is still in progress. Try again in a moment.");
+const noFile = () => localRefusal("VALIDATION", "Choose a document first.");
+
+function signingRoundsClientOrThrow(ctx, hookName) {
+  const rounds = ctx.filestore && ctx.filestore.signingRounds;
+  if (!rounds || typeof rounds.overview !== "function") {
+    throw new Error(
+      `${hookName}: host did not inject a filestore client (ctx.filestore.signingRounds)`,
+    );
+  }
+  return rounds;
+}
+
+const NO_OVERVIEW = Object.freeze({ byFileId: Object.freeze(Object.create(null)), roundsEnabled: null });
+
+/**
+ * What the signed-in user may know about the signing round of each file in
+ * `fileIds`, in one batched read. Returns `{ byFileId, roundsEnabled,
+ * loading, error, refresh }`. `byFileId[id]` is `{ file_id, can_manage,
+ * can_prepare, round, locked }`; a file the user cannot see has no entry.
+ * `roundsEnabled` is false when the workspace cannot start signing rounds,
+ * and null until the first answer. Refetches only when the set of ids, or the
+ * signed-in user, changes.
+ */
+export function useSigningRounds(fileIds) {
+  const ctx = useWidgetContextOrThrow("useSigningRounds");
+  const roundsRef = useRef(null);
+  roundsRef.current = signingRoundsClientOrThrow(ctx, "useSigningRounds");
+  const key = uniqueFileIds(fileIds).join(",");
+  const scope = `${userIdOf(ctx)}|${key}`;
+  const askRef = useRef(null);
+  askRef.current = { scope, key, asked: fileIds };
+  const runRef = useRef(0);
+
+  const [held, setHeld] = useState({ scope, overview: NO_OVERVIEW, error: null, settled: key === "" });
+  const [refreshing, setRefreshing] = useState(false);
+
+  const refresh = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { scope: forScope, key: forKey, asked } = askRef.current;
+    const ids = forKey ? forKey.split(",") : [];
+    if (ids.length === 0) {
+      setHeld({ scope: forScope, overview: NO_OVERVIEW, error: null, settled: true });
+      setRefreshing(false);
+      return;
+    }
+    setRefreshing(true);
+    try {
+      const pages = await Promise.all(chunkFileIds(ids).map((chunk) => roundsRef.current.overview(chunk)));
+      if (runRef.current !== myRun) return;
+      setHeld({ scope: forScope, overview: indexOverview(pages, asked), error: null, settled: true });
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      const error = toSigningRoundError(err);
+      // What was read before stays, but only if it was read for these files.
+      setHeld((previous) => ({
+        scope: forScope,
+        overview: previous.scope === forScope ? previous.overview : NO_OVERVIEW,
+        error,
+        settled: true,
+      }));
+    }
+    setRefreshing(false);
+  }, []);
+
+  useEffect(() => {
+    refresh();
+  }, [scope, refresh]);
+
+  const current = held.scope === scope ? held : { overview: NO_OVERVIEW, error: null, settled: key === "" };
+  return {
+    byFileId: current.overview.byFileId,
+    roundsEnabled: current.overview.roundsEnabled,
+    loading: key !== "" && (!current.settled || refreshing),
+    error: current.error,
+    refresh,
+  };
+}
+
+/**
+ * One file's current signing round and the actions of whoever manages the
+ * file's folder. Returns `{ round, loading, error, refresh, prepare,
+ * preparedFile, confirm, cancel, busy }`.
+ *
+ * `prepare(signerIds)` drafts a round for those people, in the order their
+ * places appear on the signature page; `preparedFile()` answers `{ url,
+ * sha256, expires_at, size_bytes }` for the draft's document; `confirm()`
+ * opens the round for the document that `preparedFile()` last returned, so it
+ * needs no argument; `cancel()` ends a draft or an open round and resolves to
+ * the cancelled round. One action runs at a time: while `busy` is true another
+ * one is refused with code `ACTION_IN_PROGRESS`, never queued. A refused
+ * action sets `error` and rejects with it: `code` and `message` come from the
+ * server, `errors` has one entry per refused signer, `retryAfter` is the
+ * seconds to wait. When the refusal means the round is no longer what was
+ * shown, the round is read again.
+ */
+export function useSigningRound(fileId) {
+  const ctx = useWidgetContextOrThrow("useSigningRound");
+  const roundsRef = useRef(null);
+  roundsRef.current = signingRoundsClientOrThrow(ctx, "useSigningRound");
+  const scope = `${userIdOf(ctx)}|${fileId || ""}`;
+  const askRef = useRef(null);
+  askRef.current = { scope, fileId };
+  const runRef = useRef(0);
+  const busyRef = useRef(false);
+  const previewedRef = useRef(null);
+
+  const [held, setHeld] = useState({ scope, round: null, error: null, settled: !fileId });
+  const [reading, setReading] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  const current = held.scope === scope ? held : { round: null, error: null, settled: !fileId };
+  const roundRef = useRef(null);
+  roundRef.current = current.round;
+
+  /** Read the round again. `keep` is a refusal to leave on `error` while doing so. */
+  const load = useCallback(async (keep = null) => {
+    const myRun = ++runRef.current;
+    const { scope: forScope, fileId: id } = askRef.current;
+    if (!id) {
+      setHeld({ scope: forScope, round: null, error: keep, settled: true });
+      setReading(false);
+      return;
+    }
+    setReading(true);
+    try {
+      const roundId = reportedRoundId(await roundsRef.current.overview([id]), id);
+      const round = currentRoundOrNull(roundId ? await roundsRef.current.get(roundId) : null);
+      if (runRef.current !== myRun) return;
+      setHeld({ scope: forScope, round, error: keep, settled: true });
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      const error = keep || toSigningRoundError(err);
+      setHeld((previous) => ({
+        scope: forScope,
+        round: previous.scope === forScope ? previous.round : null,
+        error,
+        settled: true,
+      }));
+    }
+    setReading(false);
+  }, []);
+
+  const refresh = useCallback(() => load(), [load]);
+
+  useEffect(() => {
+    previewedRef.current = null;
+    load();
+  }, [scope, load]);
+
+  /**
+   * The one way an action runs. It refuses a second action, and it applies
+   * what the action answered only while the hook is still on the file and
+   * user it started for. `work` resolves to `{ value, round }`; a `round`
+   * (null included) replaces the shown round and outdates every read in flight.
+   */
+  const run = useCallback(
+    async (work) => {
+      if (busyRef.current) throw actionInProgress();
+      const { scope: forScope, fileId: forFile } = askRef.current;
+      const stillHere = () => askRef.current.scope === forScope;
+      busyRef.current = true;
+      setBusy(true);
+      setHeld((previous) => (previous.scope === forScope && previous.error ? { ...previous, error: null } : previous));
+      try {
+        const outcome = await work(roundsRef.current, roundRef.current, forFile);
+        if (outcome.round !== undefined && stillHere()) {
+          runRef.current += 1;
+          setReading(false);
+          setHeld({ scope: forScope, round: currentRoundOrNull(outcome.round), error: null, settled: true });
+        }
+        return outcome.value;
+      } catch (err) {
+        const refusal = toSigningRoundError(err);
+        if (stillHere()) {
+          if (roundChangedUnderneath(refusal.code)) load(refusal);
+          else setHeld((previous) => (previous.scope === forScope ? { ...previous, error: refusal } : previous));
+        }
+        throw refusal;
+      } finally {
+        busyRef.current = false;
+        setBusy(false);
+      }
+    },
+    [load],
+  );
+
+  const prepare = useCallback(
+    (signerIds) =>
+      run(async (rounds, _round, forFile) => {
+        if (!forFile) throw noFile();
+        const draft = await rounds.prepare(forFile, signerIds);
+        return { value: draft, round: draft };
+      }),
+    [run],
+  );
+
+  const preparedFile = useCallback(
+    () =>
+      run(async (rounds, round) => {
+        if (!round) throw noRound();
+        const link = await rounds.preparedFile(round.id);
+        previewedRef.current = { roundId: round.id, sha256: link.sha256 };
+        return { value: link };
+      }),
+    [run],
+  );
+
+  const confirm = useCallback(
+    () =>
+      run(async (rounds, round) => {
+        if (!round) throw noRound();
+        const previewed = previewedRef.current;
+        // Confirming names the exact document the manager was shown.
+        if (!previewed || previewed.roundId !== round.id) throw previewRequired();
+        const opened = await rounds.confirm(round.id, previewed.sha256);
+        return { value: opened, round: opened };
+      }),
+    [run],
+  );
+
+  const cancel = useCallback(
+    () =>
+      run(async (rounds, round) => {
+        if (!round) throw noRound();
+        const cancelled = await rounds.cancel(round.id);
+        return { value: cancelled, round: null };
+      }),
+    [run],
+  );
+
+  return {
+    round: current.round,
+    loading: Boolean(fileId) && (!current.settled || reading),
+    error: current.error,
+    refresh,
+    prepare,
+    preparedFile,
+    confirm,
+    cancel,
+    busy,
+  };
+}

package/dist/signing-state.js

@@ -0,0 +1,140 @@
+// The signing hooks' logic that needs no React: what a server answer does to
+// a sign order's state, what a refusal says, and how an overview is indexed.
+// Kept apart from hooks.js so it runs under plain `node --test`.
+
+/** The server reads at most this many file ids per overview call. */
+export const OVERVIEW_IDS_PER_CALL = 200;
+
+/** The user has signed; the signature is being added to the document. */
+export const SEALING_HINT = "sealing";
+
+export const NO_SIGN_ORDER = Object.freeze({
+  status: null,
+  qr: null,
+  autoStartToken: null,
+  message: null,
+  signerName: null,
+  signedAt: null,
+  hintCode: null,
+  nameRefusal: null,
+});
+
+/** The state of an order that completed before the widget mounted. */
+export const signedOrderState = () => ({ ...NO_SIGN_ORDER, status: "complete" });
+
+/** A fresh order. A resumed one arrives with the hint and message of where it stands. */
+export function signOrderStateAfterInitiate(answer) {
+  const res = answer || {};
+  return {
+    ...NO_SIGN_ORDER,
+    status: res.status || "pending",
+    qr: res.qr || null,
+    autoStartToken: res.auto_start_token || null,
+    message: res.message || null,
+    hintCode: res.hint_code || null,
+  };
+}
+
+/**
+ * One poll's answer. The hint and the name refusal describe the order as it
+ * is now, so an answer without them clears them; the other fields change only
+ * when the answer carries them. A QR code is kept only while there is
+ * something to scan.
+ */
+export function signOrderStateAfterAnswer(previous, answer) {
+  if (!answer) return previous;
+  const status = answer.status != null ? answer.status : previous.status;
+  const hintCode = answer.hint_code || null;
+  return {
+    ...previous,
+    status,
+    // Opening BankID only makes sense while the user has yet to sign.
+    autoStartToken: status === "pending" && hintCode !== SEALING_HINT ? previous.autoStartToken : null,
+    qr: answer.qr !== undefined ? answer.qr || null : status === "pending" ? previous.qr : null,
+    message: answer.message !== undefined ? answer.message || null : previous.message,
+    signerName: answer.signer_name !== undefined ? answer.signer_name || null : previous.signerName,
+    signedAt: answer.signed_at !== undefined ? answer.signed_at || null : previous.signedAt,
+    hintCode,
+    nameRefusal: answer.name_refusal || null,
+  };
+}
+
+/**
+ * The answer to a cancel is what became of the order: cancelled, or already
+ * ended, or still pending because the signature is being added to the document
+ * and can no longer be undone. A host that answers nothing cancelled it.
+ */
+export function signOrderStateAfterCancel(previous, answer) {
+  const next = signOrderStateAfterAnswer(previous, answer && answer.status ? answer : { status: "cancelled" });
+  return next.status === "cancelled" ? { ...next, qr: null, message: null } : next;
+}
+
+/**
+ * The parts of a refusal a widget shows beside its message, as the filestore
+ * client put them on its error: one entry per refused signer (`app_user_id`,
+ * `message`, and for a name `reason` and `characters`), and how many seconds
+ * to wait before trying again. An error from anywhere else has neither.
+ */
+export function readRefusalDetail(err) {
+  const errors = err && Array.isArray(err.errors) ? err.errors : [];
+  const wait = err ? err.retryAfter : null;
+  return { errors, retryAfter: typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? wait : null };
+}
+
+// The round is no longer what the widget is showing: read it again.
+const ROUND_CHANGED_CODES = new Set([
+  "SIGNING_ROUND_EXPIRED",
+  "SIGNING_ROUND_CLOSED",
+  "SIGNING_ROUND_STALE",
+  "SIGNING_ROUND_NOT_DRAFT",
+  "PREPARED_FILE_MISMATCH",
+]);
+
+export const roundChangedUnderneath = (code) => ROUND_CHANGED_CODES.has(code);
+
+/** A cancelled round is not a file's current round. */
+export const currentRoundOrNull = (round) => (round && round.status !== "CANCELLED" ? round : null);
+
+const normalId = (id) => id.toLowerCase();
+
+/** Distinct ids as the server spells them (lower case), sorted, so the same set always makes the same key. */
+export function uniqueFileIds(fileIds) {
+  if (!Array.isArray(fileIds)) return [];
+  return [...new Set(fileIds.filter((id) => typeof id === "string" && id).map(normalId))].sort();
+}
+
+export function chunkFileIds(ids, size = OVERVIEW_IDS_PER_CALL) {
+  const chunks = [];
+  for (let i = 0; i < ids.length; i += size) chunks.push(ids.slice(i, i + size));
+  return chunks;
+}
+
+/**
+ * Overview pages as `{ byFileId, roundsEnabled }`. A file the caller cannot
+ * see has no entry. `roundsEnabled` is false as soon as one page says so.
+ * `byFileId` has no prototype, so no file id can collide with an inherited
+ * name; an id the caller spelled in another case finds the same entry.
+ */
+export function indexOverview(pages, askedIds = []) {
+  const byFileId = Object.create(null);
+  let roundsEnabled = pages.length > 0;
+  for (const page of pages) {
+    for (const entry of (page && Array.isArray(page.data) ? page.data : [])) {
+      if (entry && typeof entry.file_id === "string" && entry.file_id) byFileId[entry.file_id] = entry;
+    }
+    if (!page || !page.meta || page.meta.rounds_enabled !== true) roundsEnabled = false;
+  }
+  for (const asked of Array.isArray(askedIds) ? askedIds : []) {
+    if (typeof asked !== "string" || asked in byFileId) continue;
+    const entry = byFileId[normalId(asked)];
+    if (entry) byFileId[asked] = entry;
+  }
+  return { byFileId, roundsEnabled };
+}
+
+/** The id of the round the overview reports for `fileId`, or null. */
+export function reportedRoundId(overview, fileId) {
+  if (typeof fileId !== "string") return null;
+  const entry = indexOverview([overview], [fileId]).byFileId[fileId];
+  return entry && entry.round && entry.round.id ? entry.round.id : null;
+}

package/package.json

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