@beyondwork/docx-react-component 1.0.41 → 1.0.42

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

@@ -0,0 +1,311 @@
+import type {
+  CommentAttachment,
+  CommentAudience,
+  CommentBody,
+  CommentLabel,
+  CommentMention,
+  CommentPresentation,
+  CommentPresentationReply,
+  CommentPresentationSnapshot,
+  CommentReaction,
+} from "../../api/comment-presentation-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  firstChild,
+  parseBwXml,
+  renderCdata,
+  renderElement,
+  renderText,
+  stripNs,
+  textOf,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+const AUDIENCE_VOCAB = new Set<CommentAudience>([
+  "internal",
+  "external",
+  "shared",
+]);
+const ATTACHMENT_KIND_VOCAB = new Set<CommentAttachment["kind"]>([
+  "image",
+  "file",
+  "link",
+]);
+
+export function buildCommentPresentationXml(
+  snap: CommentPresentationSnapshot,
+): string {
+  const entries = snap.entries.map(buildComment).join("");
+  return renderElement(
+    "bw:commentPresentation",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(snap.schemaVersion),
+    },
+    [entries],
+  );
+}
+
+function buildComment(entry: CommentPresentation): string {
+  const body = buildBody("bw:body", entry.body);
+  const replies = entry.replies.length
+    ? renderElement("bw:replies", {}, [
+        entry.replies.map(buildReply).join(""),
+      ])
+    : "";
+  const mentions = entry.mentions.length
+    ? renderElement("bw:mentions", {}, [
+        entry.mentions
+          .map((m) =>
+            renderElement("bw:mention", {
+              userId: m.userId,
+              displayName: m.displayName,
+              offsetInBody: String(m.offsetInBody),
+              entryId: m.entryId,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+  const attachments = entry.attachments.length
+    ? renderElement("bw:attachments", {}, [
+        entry.attachments.map(buildAttachment).join(""),
+      ])
+    : "";
+  const reactions = entry.reactions.length
+    ? renderElement("bw:reactions", {}, [
+        entry.reactions
+          .map((r) =>
+            renderElement("bw:reaction", {
+              emoji: r.emoji,
+              authorId: r.authorId,
+              reactedAt: r.reactedAt,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+  const labels = entry.labels.length
+    ? renderElement("bw:labels", {}, [
+        entry.labels
+          .map((l) =>
+            renderElement("bw:label", { key: l.key, color: l.color }, [
+              renderText(l.text),
+            ]),
+          )
+          .join(""),
+      ])
+    : "";
+
+  return renderElement(
+    "bw:comment",
+    {
+      commentId: entry.commentId,
+      audience: entry.audience,
+    },
+    [body, replies, mentions, attachments, reactions, labels],
+  );
+}
+
+function buildReply(reply: CommentPresentationReply): string {
+  return renderElement("bw:reply", { entryId: reply.entryId }, [
+    buildBody("bw:body", reply.body),
+  ]);
+}
+
+function buildBody(elementName: string, body: CommentBody): string {
+  const needsCdata = /[<>&]/.test(body.text);
+  return renderElement(
+    elementName,
+    {
+      format: body.format,
+      digest: body.digest,
+      sanitized: body.sanitized ? "true" : undefined,
+    },
+    [needsCdata ? renderCdata(body.text) : renderText(body.text)],
+  );
+}
+
+function buildAttachment(a: CommentAttachment): string {
+  return renderElement("bw:attachment", {
+    id: a.id,
+    kind: a.kind,
+    displayName: a.displayName,
+    mimeType: a.mimeType,
+    relationshipId: a.relationshipId,
+    href: a.href,
+    byteLength: a.byteLength !== undefined ? String(a.byteLength) : undefined,
+    width: a.width !== undefined ? String(a.width) : undefined,
+    height: a.height !== undefined ? String(a.height) : undefined,
+  });
+}
+
+export function parseCommentPresentationXml(
+  xml: string,
+): CommentPresentationSnapshot {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "commentPresentation") {
+    throw new Error(
+      `parseCommentPresentationXml: expected <bw:commentPresentation>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion = attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    return { schemaVersion: 1, entries: [] };
+  }
+
+  const entries: CommentPresentation[] = [];
+  for (const commentEl of childrenOf(root, "comment")) {
+    const commentId = commentEl.attributes["commentId"] ?? "";
+    if (!commentId) continue;
+    const audienceAttr = commentEl.attributes["audience"] as CommentAudience;
+    const audience: CommentAudience = AUDIENCE_VOCAB.has(audienceAttr)
+      ? audienceAttr
+      : "internal"; // fail-closed per schema
+    const bodyEl = firstChild(commentEl, "body");
+    const body: CommentBody = bodyEl ? parseBody(bodyEl) : emptyBody();
+
+    entries.push({
+      commentId,
+      audience,
+      body,
+      replies: parseReplies(commentEl),
+      mentions: parseMentions(commentEl),
+      attachments: parseAttachments(commentEl),
+      reactions: parseReactions(commentEl),
+      labels: parseLabels(commentEl),
+    });
+  }
+
+  return { schemaVersion: 1, entries };
+}
+
+function parseBody(el: ReturnType<typeof parseBwXml>): CommentBody {
+  const body: CommentBody = {
+    format: "markdown",
+    text: textOf(el),
+    digest: el.attributes["digest"] ?? "",
+  };
+  if (el.attributes["sanitized"] === "true") body.sanitized = true;
+  return body;
+}
+
+function emptyBody(): CommentBody {
+  return {
+    format: "markdown",
+    text: "",
+    digest: "",
+  };
+}
+
+function parseReplies(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentPresentationReply[] {
+  const container = firstChild(commentEl, "replies");
+  if (!container) return [];
+  const out: CommentPresentationReply[] = [];
+  for (const el of childrenOf(container, "reply")) {
+    const entryId = el.attributes["entryId"];
+    if (!entryId) continue;
+    const bodyEl = firstChild(el, "body");
+    out.push({
+      entryId,
+      body: bodyEl ? parseBody(bodyEl) : emptyBody(),
+    });
+  }
+  return out;
+}
+
+function parseMentions(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentMention[] {
+  const container = firstChild(commentEl, "mentions");
+  if (!container) return [];
+  const out: CommentMention[] = [];
+  for (const el of childrenOf(container, "mention")) {
+    const userId = el.attributes["userId"];
+    const displayName = el.attributes["displayName"];
+    const offsetInBody = attrNumber(el.attributes["offsetInBody"]);
+    if (!userId || !displayName || offsetInBody === undefined) continue;
+    const mention: CommentMention = { userId, displayName, offsetInBody };
+    if (el.attributes["entryId"] !== undefined) {
+      mention.entryId = el.attributes["entryId"];
+    }
+    out.push(mention);
+  }
+  return out;
+}
+
+function parseAttachments(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentAttachment[] {
+  const container = firstChild(commentEl, "attachments");
+  if (!container) return [];
+  const out: CommentAttachment[] = [];
+  for (const el of childrenOf(container, "attachment")) {
+    const id = el.attributes["id"];
+    const kind = el.attributes["kind"] as CommentAttachment["kind"];
+    const displayName = el.attributes["displayName"];
+    if (!id || !displayName || !ATTACHMENT_KIND_VOCAB.has(kind)) continue;
+    const a: CommentAttachment = { id, kind, displayName };
+    if (el.attributes["mimeType"] !== undefined) {
+      a.mimeType = el.attributes["mimeType"];
+    }
+    if (el.attributes["relationshipId"] !== undefined) {
+      a.relationshipId = el.attributes["relationshipId"];
+    }
+    if (el.attributes["href"] !== undefined && isAllowedHref(el.attributes["href"])) {
+      a.href = el.attributes["href"];
+    }
+    const byteLength = attrNumber(el.attributes["byteLength"]);
+    if (byteLength !== undefined) a.byteLength = byteLength;
+    const width = attrNumber(el.attributes["width"]);
+    if (width !== undefined) a.width = width;
+    const height = attrNumber(el.attributes["height"]);
+    if (height !== undefined) a.height = height;
+    out.push(a);
+  }
+  return out;
+}
+
+function isAllowedHref(href: string): boolean {
+  return (
+    href.startsWith("http://") ||
+    href.startsWith("https://") ||
+    href.startsWith("mailto:")
+  );
+}
+
+function parseReactions(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentReaction[] {
+  const container = firstChild(commentEl, "reactions");
+  if (!container) return [];
+  const out: CommentReaction[] = [];
+  for (const el of childrenOf(container, "reaction")) {
+    const emoji = el.attributes["emoji"];
+    const authorId = el.attributes["authorId"];
+    const reactedAt = el.attributes["reactedAt"];
+    if (!emoji || !authorId || !reactedAt) continue;
+    out.push({ emoji, authorId, reactedAt });
+  }
+  return out;
+}
+
+function parseLabels(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentLabel[] {
+  const container = firstChild(commentEl, "labels");
+  if (!container) return [];
+  const out: CommentLabel[] = [];
+  for (const el of childrenOf(container, "label")) {
+    const key = el.attributes["key"];
+    if (!key) continue;
+    const label: CommentLabel = { key, text: textOf(el) };
+    if (el.attributes["color"] !== undefined) label.color = el.attributes["color"];
+    out.push(label);
+  }
+  return out;
+}

package/src/io/ooxml/external-custody-payload.ts

@@ -0,0 +1,102 @@
+import type { ExternalCustody } from "../../api/external-custody-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  parseBwXml,
+  renderElement,
+  stripNs,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+export function buildExternalCustodyXml(custody: ExternalCustody): string {
+  const stripped = renderElement("bw:strippedComments", {}, [
+    custody.strippedCommentIds
+      .map((id) => renderElement("bw:commentRef", { commentId: id }))
+      .join(""),
+  ]);
+  const participants = custody.strippedParticipantIds.length
+    ? renderElement("bw:strippedParticipants", {}, [
+        custody.strippedParticipantIds
+          .map((id) => renderElement("bw:userRef", { id }))
+          .join(""),
+      ])
+    : "";
+  return renderElement(
+    "bw:externalCustody",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(custody.schemaVersion),
+      custodyId: custody.custodyId,
+      originDocumentId: custody.originDocumentId,
+      originPayloadId: custody.originPayloadId,
+      originContentHash: custody.originContentHash,
+      sentAt: custody.sentAt,
+      sentBy: custody.sentBy,
+      recipient: custody.recipient,
+      archiveRef: custody.archiveRef,
+    },
+    [stripped, participants],
+  );
+}
+
+export function parseExternalCustodyXml(xml: string): ExternalCustody {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "externalCustody") {
+    throw new Error(
+      `parseExternalCustodyXml: expected <bw:externalCustody>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion = attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    throw new Error(
+      `parseExternalCustodyXml: unsupported schemaVersion=${schemaVersion}`,
+    );
+  }
+
+  const required = [
+    "custodyId",
+    "originDocumentId",
+    "originPayloadId",
+    "originContentHash",
+    "sentAt",
+    "sentBy",
+    "recipient",
+    "archiveRef",
+  ] as const;
+  for (const key of required) {
+    if (!root.attributes[key]) {
+      throw new Error(
+        `parseExternalCustodyXml: missing required attribute ${key}`,
+      );
+    }
+  }
+
+  const strippedContainer = childrenOf(root, "strippedComments")[0];
+  const strippedCommentIds = strippedContainer
+    ? childrenOf(strippedContainer, "commentRef")
+        .map((el) => el.attributes["commentId"])
+        .filter((id): id is string => Boolean(id))
+    : [];
+
+  const participantsContainer = childrenOf(root, "strippedParticipants")[0];
+  const strippedParticipantIds = participantsContainer
+    ? childrenOf(participantsContainer, "userRef")
+        .map((el) => el.attributes["id"])
+        .filter((id): id is string => Boolean(id))
+    : [];
+
+  return {
+    schemaVersion: 1,
+    custodyId: root.attributes["custodyId"]!,
+    originDocumentId: root.attributes["originDocumentId"]!,
+    originPayloadId: root.attributes["originPayloadId"]!,
+    originContentHash: root.attributes["originContentHash"]!,
+    sentAt: root.attributes["sentAt"]!,
+    sentBy: root.attributes["sentBy"]!,
+    recipient: root.attributes["recipient"]!,
+    archiveRef: root.attributes["archiveRef"]!,
+    strippedCommentIds,
+    strippedParticipantIds,
+  };
+}

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

@@ -0,0 +1,97 @@
+import type {
+  AuthorKind,
+  Participant,
+  ParticipantRole,
+  ParticipantRoster,
+} from "../../api/participants-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  parseBwXml,
+  renderElement,
+  stripNs,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+const ROLE_VOCAB = new Set<ParticipantRole>([
+  "author",
+  "reviewer",
+  "observer",
+]);
+const KIND_VOCAB = new Set<AuthorKind>(["human", "agent", "system"]);
+
+export function buildParticipantsXml(roster: ParticipantRoster): string {
+  const rows = roster.entries.map(buildRow).join("");
+  return renderElement(
+    "bw:participants",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(roster.schemaVersion),
+    },
+    [rows],
+  );
+}
+
+function buildRow(p: Participant): string {
+  return renderElement("bw:participant", {
+    userId: p.userId,
+    email: p.email,
+    displayName: p.displayName,
+    collabIdentity: p.collabIdentity,
+    authorKind: p.authorKind,
+    role: p.role,
+    organization: p.organization,
+    avatarHref: p.avatarHref,
+  });
+}
+
+export function parseParticipantsXml(xml: string): ParticipantRoster {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "participants") {
+    throw new Error(
+      `parseParticipantsXml: expected <bw:participants>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion = attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    return { schemaVersion: 1, entries: [] };
+  }
+
+  const entries: Participant[] = [];
+  for (const el of childrenOf(root, "participant")) {
+    const userId = el.attributes["userId"];
+    const email = el.attributes["email"];
+    const displayName = el.attributes["displayName"];
+    const collabIdentity = el.attributes["collabIdentity"];
+    const authorKind = el.attributes["authorKind"] as AuthorKind;
+    if (
+      !userId ||
+      !email ||
+      !displayName ||
+      !collabIdentity ||
+      !KIND_VOCAB.has(authorKind)
+    ) {
+      continue;
+    }
+    const row: Participant = {
+      userId,
+      email: email.toLowerCase(),
+      displayName,
+      collabIdentity,
+      authorKind,
+    };
+    const role = el.attributes["role"] as ParticipantRole | undefined;
+    if (role !== undefined && ROLE_VOCAB.has(role)) row.role = role;
+    if (el.attributes["organization"] !== undefined) {
+      row.organization = el.attributes["organization"];
+    }
+    const avatarHref = el.attributes["avatarHref"];
+    if (avatarHref !== undefined && avatarHref.startsWith("https://")) {
+      row.avatarHref = avatarHref;
+    }
+    entries.push(row);
+  }
+
+  return { schemaVersion: 1, entries };
+}

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

@@ -0,0 +1,112 @@
+import { canonicalizePayload } from "./canonicalize-payload.ts";
+
+export type SignatureAlgorithm = "hmac-sha256" | "ed25519";
+
+export interface PayloadSignature {
+  algorithm: SignatureAlgorithm;
+  keyId: string;
+  signedAt: string;
+  canonicalizationProfile: "bw-canon/1";
+  value: string; // base64
+}
+
+export interface PayloadSigner {
+  keyId: string;
+  algorithm: SignatureAlgorithm;
+  sign(canonicalBytes: Uint8Array): Promise<Uint8Array>;
+}
+
+export interface PayloadVerifier {
+  verify(
+    canonicalBytes: Uint8Array,
+    signature: PayloadSignature,
+  ): Promise<boolean>;
+}
+
+export async function signWorkflowPayloadXml(
+  xml: string,
+  signer: PayloadSigner,
+  now: string = new Date().toISOString(),
+): Promise<PayloadSignature> {
+  const bytes = canonicalizePayload(xml);
+  const sig = await signer.sign(bytes);
+  return {
+    algorithm: signer.algorithm,
+    keyId: signer.keyId,
+    signedAt: now,
+    canonicalizationProfile: "bw-canon/1",
+    value: base64Encode(sig),
+  };
+}
+
+export async function verifyWorkflowPayloadXml(
+  xml: string,
+  sig: PayloadSignature,
+  verifier: PayloadVerifier,
+): Promise<boolean> {
+  if (sig.canonicalizationProfile !== "bw-canon/1") return false;
+  const bytes = canonicalizePayload(xml);
+  return verifier.verify(bytes, sig);
+}
+
+// HMAC-SHA256 helpers ----------------------------------------------------
+
+/**
+ * Builds a signer + verifier pair backed by WebCrypto HMAC-SHA256.
+ * Integration tests use this; production hosts should wire a real key store.
+ */
+export async function createHmacSigner(args: {
+  keyId: string;
+  secret: Uint8Array;
+}): Promise<PayloadSigner> {
+  const key = await importHmacKey(args.secret, ["sign"]);
+  return {
+    keyId: args.keyId,
+    algorithm: "hmac-sha256",
+    async sign(bytes) {
+      const out = await globalThis.crypto.subtle.sign("HMAC", key, bytes as BufferSource);
+      return new Uint8Array(out);
+    },
+  };
+}
+
+export async function createHmacVerifier(
+  secret: Uint8Array,
+): Promise<PayloadVerifier> {
+  const key = await importHmacKey(secret, ["verify"]);
+  return {
+    async verify(bytes, sig) {
+      if (sig.algorithm !== "hmac-sha256") return false;
+      const raw = base64Decode(sig.value);
+      return globalThis.crypto.subtle.verify("HMAC", key, raw as BufferSource, bytes as BufferSource);
+    },
+  };
+}
+
+async function importHmacKey(
+  secret: Uint8Array,
+  usages: KeyUsage[],
+): Promise<CryptoKey> {
+  return globalThis.crypto.subtle.importKey(
+    "raw",
+    secret as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    usages,
+  );
+}
+
+// base64 ------------------------------------------------------------------
+
+function base64Encode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function base64Decode(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}