@brightbeamai/chap-coordinator 0.2.9 → 0.2.12

package/README.md

@@ -216,7 +216,12 @@ task's `assignee`.
 
 Audit entries are hash-linked when the profile is active.
 `audit.verify_chain` replays the chain locally and confirms
-`prev_hash` continuity.
+`prev_hash` continuity. The verdict names the range it covered:
+`status` is `verified` with `ok: true` only when every entry was
+checked, and `not_evaluated` with `ok: false` when part of the log
+lies outside the chain, which happens when the profile is added to a
+workspace that already has entries. A broken chain is an error. Read
+`status`, or read `ok` and fail closed.
 
 `audit.submit_to_scitt` builds a SCITT-shaped signed statement for
 each audit entry in the requested range and passes it to a

package/dist/{api-CPEk0V6i.d.ts → api-BOGEBNmX.d.ts}

@@ -75,6 +75,8 @@ interface CoordinatorOptions {
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
+    /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
+    maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;
@@ -175,6 +177,19 @@ declare class Coordinator {
     private opTaskComplete;
     private opAuditRead;
     private opReviewRequest;
+    /**
+     * Verify an optional `approved_artefact_digest` against the artefact under
+     * review (review/1.0 S3.2).
+     *
+     * The digest sits in params, so it is inside whatever the envelope signature
+     * covers: the decision then attests the content the reviewer saw rather than
+     * a task reference, and a relying party can check it without trusting the
+     * Coordinator that produced it. Absent, behaviour is exactly as before.
+     *
+     * On mismatch nothing is recorded and no state changes, so a client that
+     * computes the wrong digest refuses only its own decision.
+     */
+    private checkArtefactDigest;
     private opDecide;
     private opDecideOverride;
     private opAbstainDeclare;

package/dist/{api-DE78DA0o.d.cts → api-DiiL0sil.d.cts}

@@ -75,6 +75,8 @@ interface CoordinatorOptions {
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
+    /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
+    maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;
@@ -175,6 +177,19 @@ declare class Coordinator {
     private opTaskComplete;
     private opAuditRead;
     private opReviewRequest;
+    /**
+     * Verify an optional `approved_artefact_digest` against the artefact under
+     * review (review/1.0 S3.2).
+     *
+     * The digest sits in params, so it is inside whatever the envelope signature
+     * covers: the decision then attests the content the reviewer saw rather than
+     * a task reference, and a relying party can check it without trusting the
+     * Coordinator that produced it. Absent, behaviour is exactly as before.
+     *
+     * On mismatch nothing is recorded and no state changes, so a client that
+     * computes the wrong digest refuses only its own decision.
+     */
+    private checkArtefactDigest;
     private opDecide;
     private opDecideOverride;
     private opAbstainDeclare;

package/dist/api.d.cts

@@ -1,4 +1,4 @@
 import './methods.cjs';
-export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-DE78DA0o.cjs';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-DiiL0sil.cjs';
 import './types.cjs';
 import './storage/store.cjs';

package/dist/api.d.ts

@@ -1,4 +1,4 @@
 import './methods.js';
-export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-CPEk0V6i.js';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-BOGEBNmX.js';
 import './types.js';
 import './storage/store.js';

package/dist/index.cjs

@@ -259,6 +259,7 @@ var E = {
   NOT_AUTHORISED: -32011,
   PATCH_FAILED: -32012,
   REVIEW_LAPSED: -32013,
+  REVIEW_ALREADY_OPEN: -32014,
   // whisper/1.0 profile (profiles/whisper.md S6)
   WHISPER_ALREADY_ANSWERED: -32020,
   WHISPER_LAPSED: -32021,
@@ -285,6 +286,7 @@ var E = {
   SIG_KEY_NOT_FOUND: -32071,
   SIG_KEY_REVOKED: -32072,
   SIG_ROTATION_KEY_MISMATCH: -32073,
+  SIG_ARTEFACT_DIGEST_MISMATCH: -32074,
   // audit-scitt/1.0 profile (profiles/audit-scitt.md S8)
   SCITT_UNREACHABLE: -32080,
   SCITT_STATEMENT_REJECTED: -32081,
@@ -321,6 +323,11 @@ function isValidEnvelope(env) {
 var PatchError = class extends Error {
 };
 var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var ARRAY_INDEX_RE = /^(0|[1-9][0-9]*)$/;
+function arrayIndex(seg) {
+  if (!ARRAY_INDEX_RE.test(seg)) throw new PatchError(`Array index expected at ${JSON.stringify(seg)}`);
+  return Number(seg);
+}
 function unescape(token) {
   return token.replace(/~1/g, "/").replace(/~0/g, "~");
 }
@@ -345,8 +352,8 @@ function navigate(doc, parts) {
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
     if (Array.isArray(parent)) {
-      const idx = Number(part);
-      if (!Number.isInteger(idx) || idx < 0 || idx >= parent.length) {
+      const idx = arrayIndex(part);
+      if (idx >= parent.length) {
         throw new PatchError(`Index out of range at /${parts.slice(0, i + 1).join("/")}`);
       }
       parent = parent[idx];
@@ -362,11 +369,7 @@ function navigate(doc, parts) {
   const last = parts[parts.length - 1];
   if (Array.isArray(parent)) {
     if (last === "-") return [parent, "-"];
-    const idx = Number(last);
-    if (!Number.isInteger(idx)) {
-      throw new PatchError(`Array index expected at ${JSON.stringify(last)}`);
-    }
-    return [parent, idx];
+    return [parent, arrayIndex(last)];
   }
   return [parent, last];
 }
@@ -752,6 +755,12 @@ function registerAuditScitt(coord) {
     if (!(ws.chain_enabled || coord.options.enableChain)) {
       return { error: rpcError(E.PARAMS, "Chain not enabled for this workspace") };
     }
+    if (p.from_seq !== void 0 || p.to_seq !== void 0) {
+      return { error: rpcError(
+        E.PARAMS,
+        "Range verification is not implemented; omit from_seq and to_seq to verify the whole log."
+      ) };
+    }
     let start = ws.audit.findIndex((e) => e.prev_hash != null);
     if (start < 0) start = ws.audit.length;
     const errors = [];
@@ -763,16 +772,35 @@ function registerAuditScitt(coord) {
       }
       prev = sha256Hex(Buffer.concat([canonicalize(e.envelope), Buffer.from(expectedPrev, "utf-8")]));
     }
-    const storedHead = ws.chain_head ?? ZERO_HASH;
+    const storedHead = ws.chain_head === void 0 || ws.chain_head === null ? ZERO_HASH : ws.chain_head;
     if (prev !== storedHead) {
       errors.push("chain_head mismatch: replay does not match stored head");
     }
     if (errors.length) {
       return { error: rpcError(E.PARAMS, errors.join("; ")) };
     }
+    const entriesTotal = ws.audit.length;
+    const entriesChecked = entriesTotal - start;
+    const entriesUnchecked = start;
+    if (entriesUnchecked > 0) {
+      return { result: {
+        status: "not_evaluated",
+        ok: false,
+        reason: "unchained_prefix",
+        entries_total: entriesTotal,
+        entries_checked: entriesChecked,
+        entries_unchecked: entriesUnchecked,
+        checked_from_seq: entriesChecked > 0 ? ws.audit[start].seq : null,
+        chain_head: storedHead
+      } };
+    }
     return { result: {
+      status: "verified",
       ok: true,
-      entries_checked: ws.audit.length - start,
+      entries_total: entriesTotal,
+      entries_checked: entriesChecked,
+      entries_unchecked: 0,
+      checked_from_seq: entriesChecked > 0 ? ws.audit[start].seq : null,
       chain_head: storedHead
     } };
   });
@@ -792,7 +820,7 @@ function registerControl(coord) {
     if (scope === "task") {
       const task = ws.tasks.get(p.task_id);
       if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
-      if (task.state === "completed" || task.state === "declined" || task.state === "cancelled") {
+      if (task.state === "completed" || task.state === "declined" || task.state === "cancelled" || task.state === "superseded") {
         return { error: rpcError(E.CONTROL_NOT_AUTHORISED, `Cannot pause ${task.state} task`) };
       }
       task.paused = true;
@@ -849,7 +877,7 @@ function registerControl(coord) {
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
     const task = ws.tasks.get(p.task_id);
     if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
-    if (task.state === "completed" || task.state === "declined" || task.state === "cancelled") {
+    if (task.state === "completed" || task.state === "declined" || task.state === "cancelled" || task.state === "superseded") {
       return { error: rpcError(E.CONTROL_NOT_AUTHORISED, `Cannot cancel ${task.state} task`) };
     }
     task.state = "cancelled";
@@ -871,7 +899,7 @@ function registerControl(coord) {
       }));
     }
     if (include.includes("open_tasks")) {
-      state.open_tasks = Array.from(ws.tasks.values()).filter((t) => t.state !== "completed" && t.state !== "declined" && t.state !== "cancelled").map((t) => ({ id: t.id, kind: t.kind, state: t.state, assignee: t.assignee }));
+      state.open_tasks = Array.from(ws.tasks.values()).filter((t) => t.state !== "completed" && t.state !== "declined" && t.state !== "cancelled" && t.state !== "superseded").map((t) => ({ id: t.id, kind: t.kind, state: t.state, assignee: t.assignee }));
     }
     if (include.includes("mode_ceiling")) state.mode_ceiling = ws.mode_ceiling;
     if (include.includes("policy")) state.routing_policy_uri = ws.routing_policy_uri;
@@ -939,6 +967,13 @@ function registerControl(coord) {
     if (!ws.members.has(assignee)) {
       return { error: rpcError(E.PARAMS, "successor assignee not in workspace") };
     }
+    const requestedMode = newSpec.mode ?? old.mode;
+    if (!modeLE(requestedMode, ws.mode_ceiling)) {
+      return { error: rpcError(
+        E.MODE_CEILING_EXCEEDED,
+        `Requested mode ${requestedMode} exceeds ceiling ${ws.mode_ceiling}`
+      ) };
+    }
     const now = coord.now();
     const newId = coord.ids.taskId();
     const newTask = {
@@ -950,7 +985,7 @@ function registerControl(coord) {
       input: newSpec.input ?? {},
       created_at: now,
       updated_at: now,
-      mode: newSpec.mode ?? old.mode,
+      mode: requestedMode,
       supersedes: old.id,
       history: [{
         ts: now,
@@ -960,6 +995,8 @@ function registerControl(coord) {
       }],
       paused: false
     };
+    if (ws.profiles.some((pr) => pr.startsWith("modes/")) && newTask.mode === "trial") newTask.review_required = true;
+    else if ("review_required" in newSpec) newTask.review_required = !!newSpec.review_required;
     ws.tasks.set(newId, newTask);
     old.state = "superseded";
     old.superseded_by = newId;
@@ -1713,6 +1750,8 @@ var READ_ONLY_METHODS = /* @__PURE__ */ new Set([
   "audit.verify_chain",
   "audit.verify_receipt"
 ]);
+var MAX_IDEMPOTENCY_KEYS = 1e4;
+var DEFAULT_MAX_ENVELOPE_BYTES = 1048576;
 function nowIso(clockMs) {
   const d = clockMs === void 0 ? /* @__PURE__ */ new Date() : new Date(clockMs);
   return d.toISOString().replace(/\.(\d{3})Z$/, ".$1Z");
@@ -1731,6 +1770,25 @@ function tagsError(p) {
 function linkHash(envelope, prev) {
   return sha256Hex(Buffer.concat([canonicalize(envelope), Buffer.from(prev, "utf-8")]));
 }
+function reviewRuleSupported(rule) {
+  if (rule === "any_one_approves" || rule === "all_approve") return true;
+  if (rule.startsWith("quorum:")) {
+    const arg = rule.slice("quorum:".length);
+    return /^[0-9]+$/.test(arg) && parseInt(arg, 10) >= 1;
+  }
+  return false;
+}
+function reviewSatisfied(review) {
+  const approvers = new Set(review.decisions.filter((d) => d.kind === "approve").map((d) => d.reviewer));
+  const rule = review.rule || "any_one_approves";
+  if (rule === "all_approve") {
+    const named = review.requested_to.filter((r) => !(r.startsWith("workspace:") || r.startsWith("group:")));
+    if (named.length === 0) return approvers.size >= 1;
+    return named.every((r) => approvers.has(r));
+  }
+  if (rule.startsWith("quorum:")) return approvers.size >= parseInt(rule.slice("quorum:".length), 10);
+  return approvers.size >= 1;
+}
 function reply(env, body) {
   const out = { jsonrpc: "2.0", id: env.id };
   if (body.error !== void 0) out.error = body.error;
@@ -1956,6 +2014,18 @@ var Coordinator = class {
     if (!isValidEnvelope(envelope) || !envelope.method) {
       return reply(envelope, { error: rpcError(E.REQUEST, "Invalid JSON-RPC 2.0 request") });
     }
+    const maxBytes = this.options.maxEnvelopeBytes ?? DEFAULT_MAX_ENVELOPE_BYTES;
+    let size = 0;
+    try {
+      size = canonicalize(envelope).length;
+    } catch {
+    }
+    if (size > maxBytes) {
+      return reply(envelope, { error: rpcError(
+        E.REQUEST,
+        `Envelope exceeds max_envelope_bytes (${size} > ${maxBytes})`
+      ) });
+    }
     const method = envelope.method;
     const rawParams = envelope.params;
     if (rawParams !== void 0 && rawParams !== null && (typeof rawParams !== "object" || Array.isArray(rawParams))) {
@@ -1980,7 +2050,7 @@ var Coordinator = class {
       const stale = this.checkStepUp(params);
       if (stale) return reply(envelope, { error: stale });
     }
-    if (method.startsWith("control.") || method.startsWith("deliberate.") || method.startsWith("handoff.")) {
+    if (method.startsWith("control.") || method.startsWith("deliberate.") || method.startsWith("handoff.") || method.startsWith("whisper.")) {
       const wsId2 = params.workspace;
       const ws = typeof wsId2 === "string" ? this.workspaces.get(wsId2) : void 0;
       if (ws) {
@@ -2089,6 +2159,9 @@ var Coordinator = class {
     if (member.keys.some((k) => k.kid === kid && k.revoked_at !== void 0 && now >= k.revoked_at)) {
       return rpcError(E.SIG_KEY_REVOKED, `Key ${kid} is revoked`);
     }
+    if (member.keys.some((k) => k.kid === kid && k.valid_until !== void 0 && now >= k.valid_until)) {
+      return rpcError(E.SIG_KEY_NOT_FOUND, `Key ${kid} is no longer valid`);
+    }
     const key = this.lookupKey(member, kid, ts);
     if (!key) {
       const revoked = member.keys.find((k) => k.kid === kid && k.revoked_at);
@@ -2104,9 +2177,8 @@ var Coordinator = class {
         return rpcError(E.SIG_VERIFY_FAILED, "Signature failed verification");
       }
       return null;
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return rpcError(E.INTERNAL, `Signature check error: ${msg}`);
+    } catch {
+      return rpcError(E.SIG_VERIFY_FAILED, "Signature failed verification");
     }
   }
   /** Lookup the key valid for a given participant at a given time. */
@@ -2230,6 +2302,7 @@ var Coordinator = class {
       state: ws.state,
       mode: ws.mode,
       mode_ceiling: ws.mode_ceiling,
+      max_envelope_bytes: this.options.maxEnvelopeBytes ?? DEFAULT_MAX_ENVELOPE_BYTES,
       step_up_window_sec: ws.step_up_window_sec,
       profiles: ws.profiles,
       members: Array.from(ws.members.values()).map(memberToDict),
@@ -2370,10 +2443,14 @@ var Coordinator = class {
       history: [{ ts: now, from: p.from, state: "created" }],
       paused: false
     };
-    if (task.mode === "trial") task.review_required = true;
+    if (ws.profiles.some((pr) => pr.startsWith("modes/")) && task.mode === "trial") task.review_required = true;
     else if ("review_required" in p) task.review_required = !!p.review_required;
     ws.tasks.set(taskId, task);
-    if (typeof p.idempotency_key === "string") ws.idempotency_keys[p.idempotency_key] = taskId;
+    if (typeof p.idempotency_key === "string") {
+      ws.idempotency_keys[p.idempotency_key] = taskId;
+      const keys = Object.keys(ws.idempotency_keys);
+      if (keys.length > MAX_IDEMPOTENCY_KEYS) delete ws.idempotency_keys[keys[0]];
+    }
     return { result: { task_id: taskId, state: "created" } };
   }
   opTaskUpdate(p) {
@@ -2387,7 +2464,7 @@ var Coordinator = class {
     const legal = {
       created: ["in_progress", "declined", "paused"],
       in_progress: ["in_progress", "completed", "declined", "review_requested", "paused"],
-      review_requested: ["in_progress", "completed", "declined"],
+      review_requested: ["in_progress"],
       paused: ["in_progress", "cancelled"]
     };
     if (!legal[task.state]?.includes(newState)) {
@@ -2413,6 +2490,30 @@ var Coordinator = class {
     if (task.state !== "created" && task.state !== "in_progress") {
       return { error: rpcError(E.PARAMS, `Cannot complete task in state: ${task.state}`) };
     }
+    if (task.review_required) {
+      const now = this.now();
+      task.pending_artefact = p.output;
+      if (!task.review) {
+        const producer = p.from;
+        const eligible = [...ws.members.keys()].filter((uri) => uri !== producer && uri !== task.assignee);
+        if (eligible.length === 0) {
+          return { error: rpcError(
+            E.NOT_AUTHORISED,
+            "Task requires review but has no eligible reviewer (needs a member other than its assignee and completer)"
+          ) };
+        }
+        task.review = { requested_at: now, requested_to: eligible, rule: "any_one_approves", decisions: [] };
+      }
+      task.state = "review_requested";
+      task.updated_at = now;
+      task.history.push({
+        ts: now,
+        from: p.from,
+        state: "review_requested",
+        note: "review required; opened on task.complete"
+      });
+      return { result: { state: "review_requested", review_id: task.id } };
+    }
     task.output = p.output;
     if (typeof p.confidence === "number" || typeof p.confidence === "string") task.confidence = p.confidence;
     task.state = "completed";
@@ -2463,12 +2564,41 @@ var Coordinator = class {
     const reviewers = Array.isArray(to) ? to : typeof to === "string" ? [to] : [];
     if (!reviewers.length) return { error: rpcError(E.PARAMS, "review.request needs 'to'") };
     const now = this.now();
+    const rule = p.rule || "any_one_approves";
+    if (!reviewRuleSupported(rule)) {
+      return { error: rpcError(E.PARAMS, `Unsupported review rule ${JSON.stringify(rule)}: review/1.0 supports any_one_approves, all_approve, quorum:<n>`) };
+    }
+    if (task.state === "review_requested" && task.review) {
+      if (contentHash(task.pending_artefact) !== contentHash(p.artefact)) {
+        return { error: rpcError(
+          E.REVIEW_ALREADY_OPEN,
+          "A review is already open on this task with different content. Decide, abstain, escalate or cancel it before requesting review of a new artefact."
+        ) };
+      }
+      if (rule !== task.review.rule) {
+        return { error: rpcError(
+          E.REVIEW_ALREADY_OPEN,
+          `Cannot change the decision rule of an open review (currently ${task.review.rule})`
+        ) };
+      }
+      for (const r of reviewers) {
+        if (!task.review.requested_to.includes(r)) task.review.requested_to.push(r);
+      }
+      if (p.deadline !== void 0) task.review.deadline = p.deadline;
+      task.updated_at = now;
+      return { result: {
+        state: "review_requested",
+        review_id: task.id,
+        amended: true,
+        requested_to: [...task.review.requested_to]
+      } };
+    }
     task.state = "review_requested";
     task.updated_at = now;
     task.review = {
       requested_at: now,
       requested_to: reviewers,
-      rule: p.rule || "any_one_approves",
+      rule,
       deadline: p.deadline,
       decisions: []
     };
@@ -2476,6 +2606,37 @@ var Coordinator = class {
     task.pending_artefact = p.artefact;
     return { result: { state: "review_requested", review_id: task.id } };
   }
+  /**
+   * Verify an optional `approved_artefact_digest` against the artefact under
+   * review (review/1.0 S3.2).
+   *
+   * The digest sits in params, so it is inside whatever the envelope signature
+   * covers: the decision then attests the content the reviewer saw rather than
+   * a task reference, and a relying party can check it without trusting the
+   * Coordinator that produced it. Absent, behaviour is exactly as before.
+   *
+   * On mismatch nothing is recorded and no state changes, so a client that
+   * computes the wrong digest refuses only its own decision.
+   */
+  checkArtefactDigest(p, task) {
+    const declared = p.approved_artefact_digest;
+    if (declared === void 0 || declared === null) return null;
+    if (typeof declared !== "string") {
+      return { error: rpcError(E.PARAMS, "approved_artefact_digest must be a string") };
+    }
+    if (task.pending_artefact === void 0) {
+      return { error: rpcError(E.PARAMS, "No artefact under review to bind a digest to") };
+    }
+    const actual = contentHash(task.pending_artefact);
+    if (declared !== actual) {
+      return { error: rpcError(
+        E.SIG_ARTEFACT_DIGEST_MISMATCH,
+        "approved_artefact_digest does not match the artefact under review",
+        { declared, actual }
+      ) };
+    }
+    return null;
+  }
   opDecide(p, kind) {
     const miss = missing(p, ["workspace", "from", "task_id"]);
     if (miss) return { error: rpcError(E.PARAMS, `Missing field: ${miss}`) };
@@ -2492,6 +2653,8 @@ var Coordinator = class {
     }
     const notReviewer = this.requireReviewer(task, p.from);
     if (notReviewer) return notReviewer;
+    const digestError = this.checkArtefactDigest(p, task);
+    if (digestError) return digestError;
     const now = this.now();
     task.review.decisions.push({
       reviewer: p.from,
@@ -2501,8 +2664,10 @@ var Coordinator = class {
       tags: p.tags
     });
     if (kind === "approve") {
-      task.output = task.pending_artefact;
-      task.state = "completed";
+      if (reviewSatisfied(task.review)) {
+        task.output = task.pending_artefact;
+        task.state = "completed";
+      }
     } else {
       task.state = p.request_revision ? "in_progress" : "declined";
     }
@@ -2526,6 +2691,8 @@ var Coordinator = class {
     }
     const notReviewer = this.requireReviewer(task, p.from);
     if (notReviewer) return notReviewer;
+    const digestError = this.checkArtefactDigest(p, task);
+    if (digestError) return digestError;
     const base = task.pending_artefact;
     if (base === void 0) return { error: rpcError(E.PARAMS, "No base artefact for override") };
     let applied;