@beyondwork/docx-react-component 1.0.41 → 1.0.42

package/src/io/ooxml/canonicalize-payload.ts

@@ -0,0 +1,301 @@
+/**
+ * Canonical serialization of the `bw:workflowPayload` used as the signing
+ * surface for `bw:signature`. Called `bw-canon/1`.
+ *
+ * Rules (see bw-collab-schema-additions.md §bw:signature):
+ *   1. Remove any top-level `bw:signature` element from the tree before
+ *      serializing.
+ *   2. Sort attributes lexicographically by qualified name.
+ *   3. Normalize attribute-value whitespace: collapse runs of `\s` to a
+ *      single space, then trim.
+ *   4. Sort children of order-insensitive parents by a keyed tuple
+ *      (see `SORT_KEYED_CHILDREN`). Children of any parent not listed
+ *      retain document order.
+ *   5. Collapse empty elements to self-closing form.
+ *   6. Emit UTF-8 bytes, LF line endings (none in practice — output is
+ *      single-line), no XML declaration, no BOM.
+ *
+ * This canonicalizer is intentionally minimal — it parses only the
+ * element / attribute / text / CDATA subset the bw schema uses. It does
+ * NOT implement C14N; the contract is self-consistent (writer and
+ * reader use this same routine) and self-referential (the signature
+ * element is excluded from its own input).
+ */
+export function canonicalizePayload(xml: string): Uint8Array {
+  const tree = parseXml(xml);
+  const filtered = stripSignature(tree);
+  const out = serialize(filtered);
+  return new TextEncoder().encode(out);
+}
+
+// ----- AST ------------------------------------------------------------------
+
+export interface XmlElement {
+  kind: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+}
+
+interface XmlText {
+  kind: "text";
+  text: string;
+}
+
+type XmlNode = XmlElement | XmlText;
+
+// ----- Parse ----------------------------------------------------------------
+
+function parseXml(src: string): XmlElement {
+  let i = 0;
+  skipProlog();
+
+  const root = readElement();
+  if (!root) throw new Error("canonicalize: no root element");
+  return root;
+
+  function skipProlog(): void {
+    while (i < src.length) {
+      if (src.startsWith("<?", i)) {
+        const end = src.indexOf("?>", i);
+        if (end < 0) throw new Error("canonicalize: unterminated prolog");
+        i = end + 2;
+        continue;
+      }
+      if (src.startsWith("<!--", i)) {
+        const end = src.indexOf("-->", i);
+        if (end < 0) throw new Error("canonicalize: unterminated comment");
+        i = end + 3;
+        continue;
+      }
+      if (/\s/.test(src[i]!)) {
+        i += 1;
+        continue;
+      }
+      break;
+    }
+  }
+
+  function readElement(): XmlElement | null {
+    // Skip whitespace + comments between siblings.
+    while (i < src.length) {
+      if (src.startsWith("<!--", i)) {
+        const end = src.indexOf("-->", i);
+        if (end < 0) throw new Error("canonicalize: unterminated comment");
+        i = end + 3;
+        continue;
+      }
+      if (/\s/.test(src[i]!)) {
+        i += 1;
+        continue;
+      }
+      break;
+    }
+    if (src[i] !== "<") return null;
+    if (src.startsWith("</", i)) return null;
+    i += 1;
+
+    const nameStart = i;
+    while (i < src.length && !/[\s/>]/.test(src[i]!)) i += 1;
+    const name = src.slice(nameStart, i);
+
+    const attrs: Record<string, string> = {};
+    while (i < src.length) {
+      while (i < src.length && /\s/.test(src[i]!)) i += 1;
+      if (src[i] === "/" || src[i] === ">") break;
+      const aNameStart = i;
+      while (i < src.length && src[i] !== "=" && !/\s/.test(src[i]!)) i += 1;
+      const attrName = src.slice(aNameStart, i);
+      while (i < src.length && /\s/.test(src[i]!)) i += 1;
+      if (src[i] !== "=") {
+        attrs[attrName] = "";
+        continue;
+      }
+      i += 1;
+      while (i < src.length && /\s/.test(src[i]!)) i += 1;
+      const quote = src[i];
+      if (quote !== '"' && quote !== "'") {
+        throw new Error(`canonicalize: unquoted attr at ${i}`);
+      }
+      i += 1;
+      const vStart = i;
+      while (i < src.length && src[i] !== quote) i += 1;
+      attrs[attrName] = xmlDecode(src.slice(vStart, i));
+      i += 1;
+    }
+
+    if (src[i] === "/") {
+      i += 1;
+      if (src[i] !== ">") throw new Error("canonicalize: bad self-close");
+      i += 1;
+      return { kind: "element", name, attributes: attrs, children: [] };
+    }
+    if (src[i] !== ">") throw new Error("canonicalize: expected >");
+    i += 1;
+
+    const children: XmlNode[] = [];
+    while (i < src.length) {
+      if (src.startsWith("</", i)) {
+        i += 2;
+        const endNameStart = i;
+        while (i < src.length && src[i] !== ">") i += 1;
+        const endName = src.slice(endNameStart, i).trim();
+        if (endName !== name) {
+          throw new Error(
+            `canonicalize: mismatched close: opened <${name}> got </${endName}>`,
+          );
+        }
+        i += 1;
+        return { kind: "element", name, attributes: attrs, children };
+      }
+      if (src.startsWith("<!--", i)) {
+        const end = src.indexOf("-->", i);
+        if (end < 0) throw new Error("canonicalize: unterminated comment");
+        i = end + 3;
+        continue;
+      }
+      if (src.startsWith("<![CDATA[", i)) {
+        const end = src.indexOf("]]>", i);
+        if (end < 0) throw new Error("canonicalize: unterminated CDATA");
+        children.push({ kind: "text", text: src.slice(i + 9, end) });
+        i = end + 3;
+        continue;
+      }
+      if (src[i] === "<") {
+        const child = readElement();
+        if (child) children.push(child);
+        continue;
+      }
+      const textStart = i;
+      while (i < src.length && src[i] !== "<") i += 1;
+      const raw = src.slice(textStart, i);
+      if (raw.length > 0) {
+        children.push({ kind: "text", text: xmlDecode(raw) });
+      }
+    }
+    throw new Error(`canonicalize: unterminated <${name}>`);
+  }
+}
+
+// ----- Transform ------------------------------------------------------------
+
+function stripSignature(el: XmlElement): XmlElement {
+  return {
+    ...el,
+    children: el.children.filter(
+      (c) => !(c.kind === "element" && localName(c.name) === "signature"),
+    ),
+  };
+}
+
+const SORT_KEYED_CHILDREN: Record<string, (el: XmlElement) => string> = {
+  participants: (el) => el.attributes["userId"] ?? "",
+  votes: (el) => el.attributes["authorId"] ?? "",
+  requiredApprovers: (el) => el.attributes["id"] ?? "",
+  reactions: (el) =>
+    `${el.attributes["emoji"] ?? ""}\u0000${el.attributes["authorId"] ?? ""}`,
+  mentions: (el) =>
+    `${el.attributes["entryId"] ?? ""}\u0000${el.attributes["offsetInBody"] ?? ""}`,
+  counterProposals: (el) => el.attributes["id"] ?? "",
+  strippedComments: (el) => el.attributes["commentId"] ?? "",
+  strippedParticipants: (el) => el.attributes["id"] ?? "",
+};
+
+const CONTAINER_WITH_SORTED_ELEMENTS: Record<string, true> = {
+  commentNegotiation: true, // children keyed by commentId
+  commentPresentation: true, // children keyed by commentId
+  attachments: true, // children keyed by id
+};
+
+const CONTAINER_CHILD_KEY: Record<string, (el: XmlElement) => string> = {
+  commentNegotiation: (el) => el.attributes["commentId"] ?? "",
+  commentPresentation: (el) => el.attributes["commentId"] ?? "",
+  attachments: (el) => el.attributes["id"] ?? "",
+};
+
+function sortChildren(el: XmlElement): XmlElement {
+  const parentLocal = localName(el.name);
+  const keyFn =
+    SORT_KEYED_CHILDREN[parentLocal] ??
+    (CONTAINER_WITH_SORTED_ELEMENTS[parentLocal]
+      ? CONTAINER_CHILD_KEY[parentLocal]
+      : undefined);
+
+  const recursed = el.children.map((child) =>
+    child.kind === "element" ? sortChildren(child) : child,
+  );
+
+  if (!keyFn) {
+    return { ...el, children: recursed };
+  }
+
+  const elements = recursed.filter(
+    (c): c is XmlElement => c.kind === "element",
+  );
+  const others = recursed.filter((c) => c.kind !== "element");
+  const sorted = [...elements].sort((a, b) => {
+    const ka = keyFn(a);
+    const kb = keyFn(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+  return { ...el, children: [...others, ...sorted] };
+}
+
+// ----- Serialize ------------------------------------------------------------
+
+function serialize(el: XmlElement): string {
+  const tree = sortChildren(el);
+  return emit(tree);
+}
+
+function emit(node: XmlNode): string {
+  if (node.kind === "text") return xmlEncode(node.text);
+  const attrPairs = Object.entries(node.attributes)
+    .map(([k, v]) => [k, normalizeWhitespace(v)] as const)
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const attrStr = attrPairs
+    .map(([k, v]) => ` ${k}="${xmlEncode(v)}"`)
+    .join("");
+
+  const content = node.children
+    .map(emit)
+    .filter((s) => s.length > 0 || preservesSpace())
+    .join("");
+  if (content.length === 0) {
+    return `<${node.name}${attrStr}/>`;
+  }
+  return `<${node.name}${attrStr}>${content}</${node.name}>`;
+}
+
+function preservesSpace(): boolean {
+  return false;
+}
+
+// ----- Helpers --------------------------------------------------------------
+
+function localName(qname: string): string {
+  const colon = qname.indexOf(":");
+  return colon < 0 ? qname : qname.slice(colon + 1);
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function xmlEncode(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function xmlDecode(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}

package/src/io/ooxml/comment-negotiation-payload.ts

@@ -0,0 +1,288 @@
+import type {
+  CommentNegotiationActionType,
+  CommentNegotiationEntry,
+  CommentNegotiationSnapshot,
+  CommentNegotiationState,
+  NegotiationCounterProposal,
+  NegotiationHistoryRow,
+  NegotiationVote,
+} from "../../api/comment-negotiation-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  firstChild,
+  parseBwXml,
+  renderElement,
+  renderText,
+  stripNs,
+  textOf,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+const STATE_VOCAB = new Set<CommentNegotiationState>([
+  "proposed",
+  "negotiating",
+  "accepted",
+  "rejected",
+  "resolved",
+]);
+const VERDICT_VOCAB = new Set<NegotiationVote["verdict"]>([
+  "approve",
+  "reject",
+  "abstain",
+]);
+const ACTION_VOCAB = new Set<CommentNegotiationActionType>([
+  "propose-change",
+  "counter-propose",
+  "vote",
+  "accept",
+  "reject",
+  "lock",
+  "reopen",
+]);
+const EDIT_KIND_VOCAB = new Set<"replace" | "insert" | "delete">([
+  "replace",
+  "insert",
+  "delete",
+]);
+
+export function buildCommentNegotiationXml(
+  snap: CommentNegotiationSnapshot,
+): string {
+  const threads = snap.entries.map(buildThread).join("");
+  return renderElement(
+    "bw:commentNegotiation",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(snap.schemaVersion),
+    },
+    [threads],
+  );
+}
+
+function buildThread(entry: CommentNegotiationEntry): string {
+  const approvers = entry.requiredApprovers.length
+    ? renderElement("bw:requiredApprovers", {}, [
+        entry.requiredApprovers
+          .map((id) => renderElement("bw:userRef", { id }))
+          .join(""),
+      ])
+    : "";
+
+  const votes = entry.votes.length
+    ? renderElement("bw:votes", {}, [
+        entry.votes
+          .map((v) =>
+            renderElement("bw:vote", {
+              authorId: v.authorId,
+              verdict: v.verdict,
+              castAt: v.castAt,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+
+  const proposals = entry.counterProposals.length
+    ? renderElement("bw:counterProposals", {}, [
+        entry.counterProposals.map(buildCounterProposal).join(""),
+      ])
+    : "";
+
+  const history = entry.history.length
+    ? renderElement("bw:history", {}, [
+        entry.history
+          .map((h) =>
+            renderElement("bw:transition", {
+              from: h.from,
+              to: h.to,
+              actorId: h.actorId,
+              at: h.at,
+              action: h.action,
+              reasonCode: h.reasonCode,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+
+  return renderElement(
+    "bw:thread",
+    {
+      commentId: entry.commentId,
+      state: entry.state,
+      lockedAt: entry.lockedAt,
+      lockedBy: entry.lockedBy,
+      acceptedProposalId: entry.acceptedProposalId,
+    },
+    [approvers, votes, proposals, history],
+  );
+}
+
+function buildCounterProposal(p: NegotiationCounterProposal): string {
+  const bodyEl = renderElement("bw:body", {}, [renderText(p.body)]);
+  const edit = p.proposedRangeEdit
+    ? renderElement(
+        "bw:proposedRangeEdit",
+        {
+          kind: p.proposedRangeEdit.kind,
+          start: String(p.proposedRangeEdit.start),
+          end: String(p.proposedRangeEdit.end),
+        },
+        [p.proposedRangeEdit.text ? renderText(p.proposedRangeEdit.text) : ""],
+      )
+    : "";
+  return renderElement(
+    "bw:counterProposal",
+    {
+      id: p.id,
+      authorId: p.authorId,
+      createdAt: p.createdAt,
+      supersededBy: p.supersededBy,
+    },
+    [bodyEl, edit],
+  );
+}
+
+export function parseCommentNegotiationXml(
+  xml: string,
+): CommentNegotiationSnapshot {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "commentNegotiation") {
+    throw new Error(
+      `parseCommentNegotiationXml: expected <bw:commentNegotiation>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion =
+    attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    // Unknown major — preserve-only; return an empty snapshot so the runtime
+    // still works. The full tree is preserved by the workflow-payload emitter.
+    return { schemaVersion: 1, entries: [] };
+  }
+
+  const entries: CommentNegotiationEntry[] = [];
+  for (const thread of childrenOf(root, "thread")) {
+    const state = thread.attributes["state"] as CommentNegotiationState;
+    if (!STATE_VOCAB.has(state)) continue;
+
+    const entry: CommentNegotiationEntry = {
+      commentId: thread.attributes["commentId"] ?? "",
+      state,
+      requiredApprovers: parseApprovers(thread),
+      votes: parseVotes(thread),
+      counterProposals: parseProposals(thread),
+      history: parseHistory(thread),
+    };
+    if (thread.attributes["lockedAt"] !== undefined) {
+      entry.lockedAt = thread.attributes["lockedAt"];
+    }
+    if (thread.attributes["lockedBy"] !== undefined) {
+      entry.lockedBy = thread.attributes["lockedBy"];
+    }
+    if (thread.attributes["acceptedProposalId"] !== undefined) {
+      entry.acceptedProposalId = thread.attributes["acceptedProposalId"];
+    }
+    entries.push(entry);
+  }
+
+  return { schemaVersion: 1, entries };
+}
+
+function parseApprovers(
+  thread: ReturnType<typeof parseBwXml>,
+): string[] {
+  const container = firstChild(thread, "requiredApprovers");
+  if (!container) return [];
+  return childrenOf(container, "userRef")
+    .map((el) => el.attributes["id"])
+    .filter((id): id is string => id !== undefined && id !== "");
+}
+
+function parseVotes(thread: ReturnType<typeof parseBwXml>): NegotiationVote[] {
+  const container = firstChild(thread, "votes");
+  if (!container) return [];
+  const out: NegotiationVote[] = [];
+  for (const el of childrenOf(container, "vote")) {
+    const verdict = el.attributes["verdict"] as NegotiationVote["verdict"];
+    if (!VERDICT_VOCAB.has(verdict)) continue;
+    const authorId = el.attributes["authorId"];
+    const castAt = el.attributes["castAt"];
+    if (!authorId || !castAt) continue;
+    out.push({ authorId, verdict, castAt });
+  }
+  return out;
+}
+
+function parseProposals(
+  thread: ReturnType<typeof parseBwXml>,
+): NegotiationCounterProposal[] {
+  const container = firstChild(thread, "counterProposals");
+  if (!container) return [];
+  const out: NegotiationCounterProposal[] = [];
+  for (const el of childrenOf(container, "counterProposal")) {
+    const id = el.attributes["id"];
+    const authorId = el.attributes["authorId"];
+    const createdAt = el.attributes["createdAt"];
+    if (!id || !authorId || !createdAt) continue;
+    const bodyEl = firstChild(el, "body");
+    const editEl = firstChild(el, "proposedRangeEdit");
+    const proposal: NegotiationCounterProposal = {
+      id,
+      authorId,
+      createdAt,
+      body: bodyEl ? textOf(bodyEl) : "",
+    };
+    if (el.attributes["supersededBy"] !== undefined) {
+      proposal.supersededBy = el.attributes["supersededBy"];
+    }
+    if (editEl) {
+      const kind = editEl.attributes["kind"] as "replace" | "insert" | "delete";
+      const start = attrNumber(editEl.attributes["start"]);
+      const end = attrNumber(editEl.attributes["end"]);
+      if (EDIT_KIND_VOCAB.has(kind) && start !== undefined && end !== undefined) {
+        const edit: NegotiationCounterProposal["proposedRangeEdit"] = {
+          kind,
+          start,
+          end,
+        };
+        const text = textOf(editEl);
+        if (text.length > 0) edit.text = text;
+        proposal.proposedRangeEdit = edit;
+      }
+    }
+    out.push(proposal);
+  }
+  return out;
+}
+
+function parseHistory(
+  thread: ReturnType<typeof parseBwXml>,
+): NegotiationHistoryRow[] {
+  const container = firstChild(thread, "history");
+  if (!container) return [];
+  const out: NegotiationHistoryRow[] = [];
+  for (const el of childrenOf(container, "transition")) {
+    const from = el.attributes["from"] as CommentNegotiationState;
+    const to = el.attributes["to"] as CommentNegotiationState;
+    const action = el.attributes["action"] as CommentNegotiationActionType;
+    const actorId = el.attributes["actorId"];
+    const at = el.attributes["at"];
+    if (
+      !STATE_VOCAB.has(from) ||
+      !STATE_VOCAB.has(to) ||
+      !ACTION_VOCAB.has(action) ||
+      !actorId ||
+      !at
+    ) {
+      continue;
+    }
+    const row: NegotiationHistoryRow = { from, to, actorId, at, action };
+    if (el.attributes["reasonCode"] !== undefined) {
+      row.reasonCode = el.attributes["reasonCode"];
+    }
+    out.push(row);
+  }
+  return out;
+}