@beyondwork/docx-react-component 1.0.41 → 1.0.42

package/src/runtime/tamper-gate.ts

@@ -0,0 +1,157 @@
+import {
+  verifyWorkflowPayloadXml,
+  type PayloadSignature,
+  type PayloadVerifier,
+} from "../io/ooxml/payload-signature.ts";
+
+/**
+ * Runtime metadata-integrity states.
+ *
+ * - `unsigned`   — payload has no `bw:signature`, treated as trust-on-
+ *                  first-use. Callers may mutate freely; the first
+ *                  mutation will re-sign and transition to `verified`.
+ * - `verified`   — signature present and valid against the registered
+ *                  verifier. Mutations are allowed through the gate.
+ * - `tampered`   — signature present but verification failed. All
+ *                  mutations are blocked with `metadata_tampered` until
+ *                  the user calls `acknowledge()`.
+ */
+export type MetadataIntegrity = "unsigned" | "verified" | "tampered";
+
+export type TamperGateEvent =
+  | { type: "integrity_changed"; state: MetadataIntegrity }
+  | { type: "metadata_integrity_violation" };
+
+export interface TamperGateArgs {
+  /**
+   * Verifier used on attach. Matches the signer the host writes the
+   * payload with. Omit to skip verification (payload is treated as
+   * unsigned).
+   */
+  verifier?: PayloadVerifier;
+}
+
+export interface AttachArgs {
+  payloadXml: string;
+  signature: PayloadSignature | undefined;
+}
+
+export type GuardResult =
+  | { ok: true }
+  | { ok: false; reason: "metadata_tampered" };
+
+export interface TamperGate {
+  readonly state: MetadataIntegrity;
+  /**
+   * Verifies the signature against the supplied payload XML and
+   * transitions the gate state. Idempotent — safe to call every
+   * time a new payload is attached.
+   */
+  attach(args: AttachArgs): Promise<MetadataIntegrity>;
+  /**
+   * Resets the gate to `unsigned`. Useful when the underlying
+   * payload is detached (host switched documents).
+   */
+  detach(): void;
+  /**
+   * Single chokepoint every mutation path consults before writing
+   * back to the payload. Returns `{ ok: false, reason: "metadata_tampered" }`
+   * when the gate is in `tampered` state and the user has not
+   * acknowledged. Returns `{ ok: true }` otherwise.
+   */
+  guard(): GuardResult;
+  /**
+   * Flips `tampered` → `verified`. Only effective when the current
+   * state is `tampered`; other states are left untouched.
+   */
+  acknowledge(): void;
+  /**
+   * Re-enters `tampered` — e.g. when a host writes a payload and the
+   * re-sign check disagrees with the stored signature. Primarily for
+   * test fixtures and future composition slices.
+   */
+  flagTampered(): void;
+  subscribe(listener: (event: TamperGateEvent) => void): () => void;
+  destroy(): void;
+}
+
+export function createTamperGate(args: TamperGateArgs = {}): TamperGate {
+  let state: MetadataIntegrity = "unsigned";
+  let hasEmittedViolation = false;
+  const listeners = new Set<(event: TamperGateEvent) => void>();
+
+  const emit = (event: TamperGateEvent): void => {
+    for (const fn of [...listeners]) fn(event);
+  };
+
+  const setState = (next: MetadataIntegrity): void => {
+    if (next === state) return;
+    state = next;
+    emit({ type: "integrity_changed", state: next });
+    if (next === "tampered" && !hasEmittedViolation) {
+      hasEmittedViolation = true;
+      emit({ type: "metadata_integrity_violation" });
+    }
+    if (next !== "tampered") {
+      // Re-arm the violation emitter so a subsequent tamper transition
+      // re-notifies the host. Matches the "once per open on tamper"
+      // requirement, where "open" is bracketed by acknowledge().
+      hasEmittedViolation = false;
+    }
+  };
+
+  return {
+    get state() {
+      return state;
+    },
+
+    async attach({ payloadXml, signature }) {
+      if (!signature) {
+        setState("unsigned");
+        return state;
+      }
+      if (!args.verifier) {
+        setState("unsigned");
+        return state;
+      }
+      const ok = await verifyWorkflowPayloadXml(
+        payloadXml,
+        signature,
+        args.verifier,
+      );
+      setState(ok ? "verified" : "tampered");
+      return state;
+    },
+
+    detach() {
+      setState("unsigned");
+    },
+
+    guard() {
+      if (state === "tampered") {
+        return { ok: false, reason: "metadata_tampered" };
+      }
+      return { ok: true };
+    },
+
+    acknowledge() {
+      if (state !== "tampered") return;
+      setState("verified");
+    },
+
+    flagTampered() {
+      setState("tampered");
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    destroy() {
+      listeners.clear();
+    },
+  };
+}

package/src/runtime/workflow-markup.ts

@@ -168,6 +168,15 @@ function collectWorkflowMetadataMarkup(
       value: entry.value,
       scopeId: entry.scopeId,
       workItemId: entry.workItemId,
+      // Schema 1.1 — copy external-mode fields through so card-layer code
+      // can detect external entries without re-consulting the entry snapshot.
+      ...(entry.metadataPersistence !== undefined
+        ? { metadataPersistence: entry.metadataPersistence }
+        : {}),
+      ...(entry.storageRef !== undefined ? { storageRef: entry.storageRef } : {}),
+      ...(entry.metadataVersion !== undefined
+        ? { metadataVersion: entry.metadataVersion }
+        : {}),
     } satisfies WorkflowMetadataMarkup];
   });
 }

package/src/runtime/workflow-rail-segments.ts

@@ -16,14 +16,18 @@ import type {
   EditorAnchorProjection,
   EditorStoryTarget,
   IssueMetadataValue,
+  ReviewActionMetadataValue,
   ScopeCardModel,
+  ScopeMetadataResolver,
+  SuggestionGroup,
+  SuggestionsSnapshot,
   WorkflowBlockedCommandReason,
   WorkflowCandidateRange,
   WorkflowLockedZone,
   WorkflowMetadataMarkup,
   WorkflowScope,
 } from "../api/public-types";
-import { ISSUE_METADATA_ID } from "../api/public-types";
+import { ISSUE_METADATA_ID, REVIEW_ACTION_METADATA_ID } from "../api/public-types";
 import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
 import type { RuntimePageGraph } from "./layout/page-graph.ts";
 import type {
@@ -316,6 +320,41 @@ export interface AttachScopeCardModelInput {
    * rects — chrome consumers fall back to on-render positioning.
    */
   anchorIndex?: RenderAnchorIndex | null;
+  /**
+   * R3 — suggestion snapshot. Groups whose `issueId` matches the
+   * scope's issue attach as `ScopeCardModel.suggestionGroups`; their
+   * ids land in `suggestionGroupIds` as a convenience for consumers
+   * that want a flat lookup.
+   */
+  suggestions?: SuggestionsSnapshot | null;
+  /**
+   * K1-light — review-action markup. Entries with
+   * `metadataId === REVIEW_ACTION_METADATA_ID` whose coerced value's
+   * `issueId` matches the scope's issue attach newest-first as
+   * `ScopeCardModel.reviewActions`.
+   */
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  /**
+   * K2 — candidate ranges. Any entry with `source: "ai"` whose
+   * offset range overlaps the segment flips `agentPending` to true.
+   */
+  candidates?: readonly WorkflowCandidateRange[];
+  /**
+   * Pre-resolved external metadata values, keyed by entryId.  When an
+   * entry in `metadata` or `reviewActionMetadata` has
+   * `metadataPersistence === "external"` and its inline `value` is
+   * undefined, this map supplies the resolved value (fetched by the caller
+   * via `ScopeMetadataResolver.resolve`).
+   *
+   * Entries absent from the map render as if the metadata had no value —
+   * the card still shows the scope but drops the issue row, consistent with
+   * how malformed metadata is handled today.
+   *
+   * NOTE: The facet's `getAllScopeCardModels()` does NOT populate this.
+   * Callers that need resolved values build the map via
+   * `buildExternalResolutions()` and call `attachScopeCardModel()` directly.
+   */
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>;
 }
 
 /**
@@ -361,11 +400,23 @@ export function attachScopeCardModel(
       segment.scopeId,
       workItemId,
       input.metadata,
+      input.externalResolutions,
     );
     const primaryAnchorRect = input.anchorIndex
       ? input.anchorIndex.bySelection(segment.fromOffset, segment.toOffset)
       : null;
 
+    const suggestionGroups = resolveSuggestionGroupsForIssue(
+      issue?.issueId,
+      input.suggestions,
+    );
+    const reviewActions = resolveReviewActionsForIssue(
+      issue?.issueId,
+      input.reviewActionMetadata,
+      input.externalResolutions,
+    );
+    const agentPending = resolveAgentPending(segment, input.candidates);
+
     models.push({
       scopeId: segment.scopeId,
       ...(workItemId ? { workItemId } : {}),
@@ -373,19 +424,103 @@ export function attachScopeCardModel(
       posture: segment.posture,
       primaryAnchorRect,
       ...(issue ? { issue } : {}),
-      suggestionGroupIds: [],
-      reviewActionCount: 0,
-      agentPending: false,
+      suggestionGroupIds: suggestionGroups.map((group) => group.groupId),
+      suggestionGroups,
+      reviewActionCount: reviewActions.length,
+      reviewActions,
+      agentPending,
     });
   }
 
   return models;
 }
 
+function resolveSuggestionGroupsForIssue(
+  issueId: string | undefined,
+  suggestions: SuggestionsSnapshot | null | undefined,
+): SuggestionGroup[] {
+  if (!issueId || !suggestions?.groups) return [];
+  return suggestions.groups.filter((group) => group.issueId === issueId);
+}
+
+function resolveReviewActionsForIssue(
+  issueId: string | undefined,
+  metadata: readonly WorkflowMetadataMarkup[] | undefined,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
+): ReviewActionMetadataValue[] {
+  if (!issueId || !metadata || metadata.length === 0) return [];
+  const result: ReviewActionMetadataValue[] = [];
+  for (const entry of metadata) {
+    if (entry.metadataId !== REVIEW_ACTION_METADATA_ID) continue;
+    const coerced = coerceReviewActionValue(effectiveMetadataValue(entry, externalResolutions));
+    if (!coerced) continue;
+    if (coerced.issueId !== issueId) continue;
+    result.push(coerced);
+  }
+  // Newest-first by createdAt ISO string (lexicographic for 8601 UTC).
+  result.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+  return result;
+}
+
+function coerceReviewActionValue(
+  value: unknown,
+): ReviewActionMetadataValue | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Partial<ReviewActionMetadataValue>;
+  if (
+    typeof candidate.reviewActionId !== "string" ||
+    typeof candidate.action !== "string" ||
+    typeof candidate.actor !== "string" ||
+    typeof candidate.actorRole !== "string" ||
+    typeof candidate.createdAt !== "string"
+  ) {
+    return undefined;
+  }
+  return candidate as ReviewActionMetadataValue;
+}
+
+function resolveAgentPending(
+  segment: ScopeRailSegment,
+  candidates: readonly WorkflowCandidateRange[] | undefined,
+): boolean {
+  if (!candidates || candidates.length === 0) return false;
+  for (const candidate of candidates) {
+    if (candidate.source !== "ai") continue;
+    const range = anchorToRuntimeRange(candidate.anchor);
+    if (!range) continue;
+    // Strict-half-open overlap: [from, to).
+    if (range.to > segment.fromOffset && range.from < segment.toOffset) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Return the effective value for a metadata markup entry.  For
+ * internal-mode entries (or entries with an inline value), returns
+ * `entry.value` directly.  For external-mode entries whose inline
+ * `value` is undefined, looks up the resolved value from the
+ * caller-supplied `externalResolutions` map keyed by `entryId`.
+ *
+ * Returns `undefined` when no value is available — callers treat this the
+ * same as malformed metadata and drop the card row silently.
+ */
+function effectiveMetadataValue(
+  entry: WorkflowMetadataMarkup,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
+): Record<string, unknown> | undefined {
+  if (entry.value !== undefined) return entry.value;
+  // External-mode entry — inline body is empty. Look up the resolved value.
+  const resolved = externalResolutions?.get(entry.entryId);
+  return resolved?.value;
+}
+
 function resolveIssueForScope(
   scopeId: string,
   workItemId: string | undefined,
   metadata: readonly WorkflowMetadataMarkup[] | undefined,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
 ): IssueMetadataValue | undefined {
   if (!metadata || metadata.length === 0) return undefined;
   for (const entry of metadata) {
@@ -397,7 +532,7 @@ function resolveIssueForScope(
     const matchesScope =
       entry.scopeId !== undefined && entry.scopeId === scopeId;
     if (!matchesWorkItem && !matchesScope) continue;
-    const coerced = coerceIssueValue(entry.value);
+    const coerced = coerceIssueValue(effectiveMetadataValue(entry, externalResolutions));
     if (coerced) return coerced;
   }
   return undefined;
@@ -426,3 +561,107 @@ function coerceIssueValue(
   }
   return candidate as IssueMetadataValue;
 }
+
+// ---------------------------------------------------------------------------
+// buildExternalResolutions — caller utility for pre-resolving external refs
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured result from `buildExternalResolutions`.  Callers that previously
+ * consumed the return value as a `Map` directly must now destructure `.resolutions`.
+ */
+export interface BuildExternalResolutionsResult {
+  /**
+   * Resolved values keyed by `entryId`.  Suitable for passing into
+   * `AttachScopeCardModelInput.externalResolutions`.
+   */
+  resolutions: Map<string, { value: Record<string, unknown>; version?: number }>;
+  /**
+   * Detected version mismatches.  Non-empty only when the caller passes
+   * `detectConflicts: true`.  Each record includes both sides' value +
+   * version so the caller can emit a `metadata_conflict_detected` event.
+   */
+  conflicts: Array<{
+    scopeId?: string;
+    entryId?: string;
+    embedded: { value?: Record<string, unknown>; version?: number } | null;
+    external: { value?: Record<string, unknown>; version?: number } | null;
+  }>;
+}
+
+/**
+ * Pre-resolve every external-mode metadata entry's value via the supplied
+ * resolver.  The returned `resolutions` map is suitable for passing into
+ * `AttachScopeCardModelInput.externalResolutions`.
+ *
+ * Internal-mode entries (where `entry.value` is already inline) are skipped.
+ * When the resolver returns `undefined` for a ref (unknown or revoked), the
+ * `entryId` is omitted from the map; the scope card then renders without that
+ * value.
+ *
+ * Both `metadata` and `reviewActionMetadata` arrays are walked so review-action
+ * rows stored externally are resolved alongside issue entries.
+ *
+ * When `detectConflicts` is `true`, the helper compares each entry's embedded
+ * `metadataVersion` against the resolver-returned version.  Any mismatch is
+ * recorded in the returned `conflicts` array.
+ *
+ * NOTE: This helper is intentionally async so callers can `await` it in the
+ * React layer before passing the map to the synchronous `attachScopeCardModel`.
+ * The layout facet's `getAllScopeCardModels()` does NOT call this — it is a
+ * React-layer concern where async is normal.
+ */
+export async function buildExternalResolutions(input: {
+  metadata: readonly WorkflowMetadataMarkup[];
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  resolver: ScopeMetadataResolver;
+  /**
+   * When `true`, the helper compares each external entry's embedded
+   * `metadataVersion` against the resolver-returned version and records a
+   * conflict for every mismatch.  Absent / `false` → `conflicts` is always
+   * empty (backwards-compatible default).
+   */
+  detectConflicts?: boolean;
+}): Promise<BuildExternalResolutionsResult> {
+  const externalEntries = [
+    ...input.metadata,
+    ...(input.reviewActionMetadata ?? []),
+  ].filter(
+    (entry) =>
+      entry.metadataPersistence === "external" &&
+      entry.value === undefined &&
+      entry.storageRef !== undefined,
+  );
+
+  const results = await Promise.all(
+    externalEntries.map(async (entry) => {
+      const resolved = await input.resolver.resolve(entry.storageRef!);
+      return resolved ? { entry, resolved } : null;
+    }),
+  );
+
+  const resolutions = new Map<string, { value: Record<string, unknown>; version?: number }>();
+  const conflicts: BuildExternalResolutionsResult["conflicts"] = [];
+
+  for (const row of results) {
+    if (!row) continue;
+    resolutions.set(row.entry.entryId, row.resolved);
+
+    if (
+      input.detectConflicts &&
+      row.entry.metadataVersion !== undefined &&
+      row.resolved.version !== undefined &&
+      row.entry.metadataVersion !== row.resolved.version
+    ) {
+      conflicts.push({
+        scopeId: row.entry.scopeId,
+        entryId: row.entry.entryId,
+        // External entries have no inline value — embedded side carries only version
+        embedded: { version: row.entry.metadataVersion },
+        external: { value: row.resolved.value, version: row.resolved.version },
+      });
+    }
+  }
+
+  return { resolutions, conflicts };
+}