@beyondwork/docx-react-component 1.0.41 → 1.0.43

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;
+}

package/src/io/ooxml/workflow-payload-validator.ts

@@ -0,0 +1,367 @@
+/**
+ * Local-path validator for bw:workflowPayload 1.0 / 1.1.
+ *
+ * This is a structural sanity check that runs inline on every import.
+ * It does NOT replace the Railway OOXML validator — that one checks
+ * package-level concerns (part types, relationship sanity, Word-spec
+ * compliance).  This validator catches malformed bw:workflowPayload
+ * content that the parser would silently strip.  Results surface to
+ * callers so tooling can log, display, or assert on them.
+ *
+ * Spec: docs/reference/bw-schema-spec.md §8.2.
+ */
+
+export type ValidatorIssueCode =
+  | "unknown_enum_value"
+  | "external_entry_missing_ref"
+  | "external_entry_body_ignored"
+  | "external_field_missing_ref"
+  | "external_field_body_ignored"
+  | "internal_entry_unexpected_storage_ref"
+  | "internal_field_unexpected_storage_ref"
+  | "unsupported_version"
+  // Schema 1.2 editor-state codes
+  | "editor_state_unknown_namespace"
+  | "editor_state_duplicate_content"
+  | "editor_state_empty_content"
+  | "editor_state_invalid_inline_json"
+  | "editor_state_missing_entry_key"
+  | "editor_state_invalid_location";
+
+export type ValidatorIssueSeverity = "error" | "warning";
+
+export interface ValidatorIssue {
+  code: ValidatorIssueCode;
+  path: string; // e.g. "bw:entry[@key='e1']"
+  severity: ValidatorIssueSeverity;
+  value?: string; // the invalid value when relevant
+  detail?: string; // optional extra context
+}
+
+const OVERLAY_PERSISTENCE_VALUES = ["internal", "external"] as const;
+const SCOPE_PERSISTENCE_VALUES = ["internal", "external", "inherit"] as const;
+
+export function validateWorkflowPayloadEnvelope(xml: string): ValidatorIssue[] {
+  const issues: ValidatorIssue[] = [];
+
+  // Root version check.
+  const versionMatch = xml.match(/<bw:workflowPayload\b[^>]*\sversion="([^"]+)"/u);
+  if (versionMatch && !/^1\.[0-9]+$/.test(versionMatch[1])) {
+    issues.push({
+      code: "unsupported_version",
+      path: "bw:workflowPayload/@version",
+      value: versionMatch[1],
+      severity: "warning",
+    });
+  }
+
+  // Overlay-level metadataPersistence.
+  const overlayMatch = xml.match(/<bw:workflowOverlay\b([^>]*)>/u);
+  let overlayEnum: "internal" | "external" | undefined;
+  if (overlayMatch) {
+    const attrs = parseAttrs(overlayMatch[1]);
+    if (attrs.metadataPersistence !== undefined) {
+      if (
+        !(OVERLAY_PERSISTENCE_VALUES as readonly string[]).includes(
+          attrs.metadataPersistence,
+        )
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: "bw:workflowOverlay/@metadataPersistence",
+          value: attrs.metadataPersistence,
+          severity: "warning",
+        });
+      } else {
+        overlayEnum = attrs.metadataPersistence as "internal" | "external";
+      }
+    }
+  }
+
+  // Each scope + its fields.
+  for (const scope of findAll(xml, /<bw:scope\b([^>]*?)>([\s\S]*?)<\/bw:scope>/gu)) {
+    const scopeAttrs = parseAttrs(scope.attrs);
+    const scopeId = scopeAttrs.id ?? "?";
+    let scopePersistence: string | undefined = scopeAttrs.metadataPersistence;
+    if (scopePersistence !== undefined) {
+      if (
+        !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(scopePersistence)
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: `bw:scope[@id='${scopeId}']/@metadataPersistence`,
+          value: scopePersistence,
+          severity: "warning",
+        });
+        scopePersistence = undefined;
+      }
+    }
+
+    // <bw:field>, two forms: self-closing and with body.
+    for (const field of findFields(scope.body)) {
+      const fieldAttrs = parseAttrs(field.attrs);
+      const fieldKey = fieldAttrs.key ?? "?";
+
+      let fieldPersistence: string | undefined = fieldAttrs.metadataPersistence;
+      if (
+        fieldPersistence !== undefined &&
+        !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(fieldPersistence)
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']/@metadataPersistence`,
+          value: fieldPersistence,
+          severity: "warning",
+        });
+        fieldPersistence = undefined;
+      }
+
+      const effective = resolveEffective({
+        overlay: overlayEnum,
+        scope: scopePersistence,
+        field: fieldPersistence,
+      });
+      const hasRef = Boolean(fieldAttrs.storageRef);
+      const hasBody = field.body.trim().length > 0;
+
+      if (effective === "external") {
+        if (!hasRef) {
+          issues.push({
+            code: "external_field_missing_ref",
+            path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+            severity: "error",
+          });
+        }
+        if (hasBody) {
+          issues.push({
+            code: "external_field_body_ignored",
+            path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+            severity: "warning",
+          });
+        }
+      } else if (effective === "internal" && hasRef) {
+        // Internal-mode fields carry their value inline.  A `storageRef` on
+        // an internal field is a stale pointer from a persistence-mode
+        // downgrade and will confuse hosts that branch on its presence.
+        issues.push({
+          code: "internal_field_unexpected_storage_ref",
+          path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+          severity: "warning",
+        });
+      }
+    }
+  }
+
+  // Schema 1.2: <bw:editorState> checks.
+  const editorStateMatch = xml.match(/<bw:editorState\b[^>]*>([\s\S]*?)<\/bw:editorState>/u);
+  if (editorStateMatch) {
+    const editorStateBody = editorStateMatch[1] ?? "";
+    const nsRe = /<bw:namespace\b([^>]*)>([\s\S]*?)<\/bw:namespace>/gu;
+    for (const nsMatch of editorStateBody.matchAll(nsRe)) {
+      const attrsStr = nsMatch[1] ?? "";
+      const nsBody = nsMatch[2] ?? "";
+      const attrs = parseAttrs(attrsStr);
+      const name = attrs.name ?? "";
+      const nsPath = `bw:editorState/bw:namespace[@name='${name}']`;
+
+      // 1. Unknown namespace name (not in closed set) → warning.
+      const knownNames = ["hostAnnotations", "workflowOverlay", "workflowMetadata", "workItems"];
+      if (!knownNames.includes(name)) {
+        issues.push({
+          code: "editor_state_unknown_namespace",
+          path: nsPath,
+          severity: "warning",
+          value: name,
+        });
+        // Still check structural rules below for forward-compat awareness.
+      }
+
+      // 2. Detect presence of storageRef and inline.
+      const hasStorageRef = /<bw:storageRef\b/u.test(nsBody);
+      const hasInline = /<bw:inline\b/u.test(nsBody);
+
+      if (hasStorageRef && hasInline) {
+        // Both present → duplicate_content error.
+        issues.push({
+          code: "editor_state_duplicate_content",
+          path: nsPath,
+          severity: "error",
+        });
+      } else if (!hasStorageRef && !hasInline) {
+        // Neither present → empty_content error.
+        issues.push({
+          code: "editor_state_empty_content",
+          path: nsPath,
+          severity: "error",
+        });
+      } else if (hasStorageRef) {
+        // 3a. storageRef checks.
+        const refMatch = nsBody.match(/<bw:storageRef\b([^>]*)\/>/u);
+        if (refMatch) {
+          const refAttrs = parseAttrs(refMatch[1] ?? "");
+          const entryKey = refAttrs.entryKey ?? "";
+          const location = refAttrs.location ?? "";
+
+          if (entryKey === "") {
+            issues.push({
+              code: "editor_state_missing_entry_key",
+              path: `${nsPath}/bw:storageRef`,
+              severity: "error",
+            });
+          }
+
+          const knownLocations = ["rowstore", "key-only"];
+          if (location !== "" && !knownLocations.includes(location)) {
+            issues.push({
+              code: "editor_state_invalid_location",
+              path: `${nsPath}/bw:storageRef/@location`,
+              severity: "warning",
+              value: location,
+            });
+          }
+        }
+      } else if (hasInline) {
+        // 3b. inline JSON parse check.
+        const inlineMatch = nsBody.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+        if (inlineMatch) {
+          const rawContent = inlineMatch[1] ?? "";
+          // Strip CDATA markers (handles split CDATA too).
+          const text = rawContent.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+          try {
+            JSON.parse(text);
+          } catch {
+            issues.push({
+              code: "editor_state_invalid_inline_json",
+              path: `${nsPath}/bw:inline`,
+              severity: "error",
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Top-level entries (bw:metadata body, outside scopes).
+  // These resolve against overlay-only (no scope context available unless
+  // the entry carries its own `scope="scope:{id}"` attribute, in which case
+  // a matching scope's override would apply — we keep this simple and just
+  // use the overlay default for entries).
+  for (const entry of findEntries(xml)) {
+    const entryAttrs = parseAttrs(entry.attrs);
+    const entryKey = entryAttrs.key ?? "?";
+
+    // Definition rows (key="definition.*") are schema descriptors, not data
+    // entries.  Their body is always the human-readable label (per §4.1) and
+    // they are never subject to external-persistence rules (§4.3 applies only
+    // to data rows, §4.2).  Skip persistence checks for them.
+    if (entryKey.startsWith("definition.")) {
+      continue;
+    }
+
+    let entryPersistence: string | undefined = entryAttrs.metadataPersistence;
+    if (
+      entryPersistence !== undefined &&
+      !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(entryPersistence)
+    ) {
+      issues.push({
+        code: "unknown_enum_value",
+        path: `bw:entry[@key='${entryKey}']/@metadataPersistence`,
+        value: entryPersistence,
+        severity: "warning",
+      });
+      entryPersistence = undefined;
+    }
+
+    const effective = resolveEffective({
+      overlay: overlayEnum,
+      scope: undefined,
+      field: entryPersistence,
+    });
+    const hasRef = Boolean(entryAttrs.storageRef);
+    const hasBody = entry.body.trim().length > 0;
+
+    if (effective === "external") {
+      if (!hasRef) {
+        issues.push({
+          code: "external_entry_missing_ref",
+          path: `bw:entry[@key='${entryKey}']`,
+          severity: "error",
+        });
+      }
+      if (hasBody) {
+        issues.push({
+          code: "external_entry_body_ignored",
+          path: `bw:entry[@key='${entryKey}']`,
+          severity: "warning",
+        });
+      }
+    } else if (effective === "internal" && hasRef) {
+      // Internal-mode entries carry their value inline.  A `storageRef` on
+      // an internal entry is a stale pointer from a persistence-mode
+      // downgrade and will confuse hosts that branch on its presence.
+      issues.push({
+        code: "internal_entry_unexpected_storage_ref",
+        path: `bw:entry[@key='${entryKey}']`,
+        severity: "warning",
+      });
+    }
+  }
+
+  return issues;
+}
+
+function parseAttrs(source: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of source.matchAll(/(\w+)="([^"]*)"/gu)) {
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+function* findAll(
+  xml: string,
+  re: RegExp,
+): Generator<{ attrs: string; body: string }> {
+  for (const m of xml.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+/**
+ * Emits each `<bw:field>` in the scope body, handling both self-closing
+ * and body-bearing forms.
+ */
+function* findFields(
+  scopeBody: string,
+): Generator<{ attrs: string; body: string }> {
+  // Match both <bw:field .../> and <bw:field ...>body</bw:field>
+  const re = /<bw:field\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:field>)/gu;
+  for (const m of scopeBody.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+/**
+ * Emits each top-level `<bw:entry>` (inside `<bw:metadata>`), handling
+ * both self-closing and body-bearing forms.  Scope-internal entries
+ * are handled by findFields — this only looks at the flat metadata list.
+ */
+function* findEntries(
+  xml: string,
+): Generator<{ attrs: string; body: string }> {
+  const re = /<bw:entry\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:entry>)/gu;
+  for (const m of xml.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+function resolveEffective(input: {
+  overlay?: "internal" | "external";
+  scope?: string;
+  field?: string;
+}): "internal" | "external" {
+  if (input.field === "internal" || input.field === "external") return input.field;
+  if (input.scope === "internal" || input.scope === "external") return input.scope;
+  if (input.overlay === "external") return "external";
+  return "internal";
+}