@brightbeamai/chap-coordinator 0.2.8 → 0.2.10

package/README.md

@@ -9,19 +9,11 @@ surface, so the two interoperate on the same JSON-RPC 2.0 wire.
 
 ## Install
 
-This package is currently distributed alongside the spec repo rather
-than published to npm. To use it directly from source in another
-TypeScript project:
-
 ```bash
-# From the chap repo root
-cd packages/coordinator
-npm pack
-# In your project
-npm install ./brightbeamai-chap-coordinator-*.tgz   # the .tgz that npm pack just produced
+npm install @brightbeamai/chap-coordinator
 ```
 
-Node 18+ required. Zero external runtime dependencies; uses Node's
+Node 20+ required. Zero external runtime dependencies; uses Node's
 built-in `crypto` for Ed25519 and JCS.
 
 ## Companion packages
@@ -33,7 +25,8 @@ A2A ecosystems:
 - [`@brightbeamai/chap-coordinator-mcp`](https://github.com/BrightbeamAI/chap/tree/main/packages/coordinator-mcp) wraps a Coordinator
   as an MCP server. Every CHAP method becomes an MCP tool named
   `chap.<method>`. Reference stdio server at
-  `reference/mcp-server-ts/`. Spec target: MCP 2025-11-25.
+  `reference/mcp-server-ts/`. Spec target: MCP 2026-07-28, serving
+  2025-11-25 clients as well.
 - [`@brightbeamai/chap-coordinator-a2a`](https://github.com/BrightbeamAI/chap/tree/main/packages/coordinator-a2a) wraps a Coordinator
   as an A2A agent. Every CHAP method becomes an `AgentSkill` on the
   Agent Card. Reference Express server at `reference/a2a-server-ts/`.
@@ -223,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
@@ -247,7 +245,7 @@ statements so the caller can submit out-of-band.
 npm test
 ```
 
-72 tests as of this release, covering Core, every profile, JCS and
+The suite covers Core, every profile, JCS and
 Ed25519 conformance vectors, signed-envelope verification, OIDC/VC
 binding, the inward wrap helpers, and an end-to-end composition test
 exercising every method handler in one workspace.

package/dist/{api-C3nkEk-B.d.cts → api-CcT_8H5j.d.cts}

@@ -74,6 +74,7 @@ interface CoordinatorOptions {
     enableChain?: boolean;
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
+    requireReadMembership?: boolean;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;
@@ -174,6 +175,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-CmSvlIqO.d.ts → api-Cvkhcalw.d.ts}

@@ -74,6 +74,7 @@ interface CoordinatorOptions {
     enableChain?: boolean;
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
+    requireReadMembership?: boolean;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;
@@ -174,6 +175,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-C3nkEk-B.cjs';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-CcT_8H5j.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-CmSvlIqO.js';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-Cvkhcalw.js';
 import './types.js';
 import './storage/store.js';

package/dist/index.cjs

@@ -210,12 +210,7 @@ var IdFactory = class {
       return this.counter * 0x9E3779B97F4A7C15n & (1n << 80n) - 1n;
     }
     const buf = new Uint8Array(10);
-    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
-      crypto.getRandomValues(buf);
-    } else {
-      const nodeCrypto = require("crypto");
-      buf.set(nodeCrypto.randomBytes(10));
-    }
+    crypto.getRandomValues(buf);
     let n = 0n;
     for (const b of buf) n = n << 8n | BigInt(b);
     return n;
@@ -264,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,
@@ -290,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,
@@ -757,6 +754,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 = [];
@@ -768,16 +771,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
     } };
   });
@@ -1558,6 +1580,16 @@ function registerSecuritySigned(coord) {
     for (const f of ["target_uri", "kid"]) {
       if (!(f in p)) return { error: rpcError(E.PARAMS, `Missing field: ${f}`) };
     }
+    const sender = p.from;
+    if (sender !== p.target_uri) {
+      const caller = sender ? ws.members.get(sender) : void 0;
+      if (!caller || caller.role !== "admin") {
+        return { error: rpcError(
+          E.NOT_AUTHORISED,
+          "Revoking another member's key requires the admin role"
+        ) };
+      }
+    }
     const member = ws.members.get(p.target_uri);
     if (!member) return { error: rpcError(E.SIG_KEY_NOT_FOUND, `Unknown target: ${p.target_uri}`) };
     const key = member.keys.find((k) => k.kid === p.kid);
@@ -1649,7 +1681,8 @@ function registerWhisper(coord) {
     prompt.answer_option = answerOption;
     prompt.answer_text = answerText;
     prompt.comment = p.comment;
-    return { result: { answered: true, whisper_id: prompt.id } };
+    p.task_id = prompt.task_id;
+    return { result: { answered: true, whisper_id: prompt.id, task_id: prompt.task_id } };
   });
   coord.checkWhisperLapses = (workspaceId, now) => {
     const ws = coord.workspaces.get(workspaceId);
@@ -1673,6 +1706,11 @@ function registerWhisper(coord) {
           ts: coord.now(),
           kind: "whisper_lapsed",
           whisper_id: prompt.id,
+          // Carry the task so a task-filtered audit.read surfaces the
+          // lapse. A lapsed whisper applies its default with no human
+          // input, so it is the case most in need of being visible on
+          // the task's thread.
+          task_id: prompt.task_id,
           default_applied: prompt.default_if_lapsed
         }
       };
@@ -1874,6 +1912,7 @@ var Coordinator = class {
         mode_ceiling: ws.mode_ceiling,
         routing_policy_uri: ws.routing_policy_uri,
         step_up_window_sec: ws.step_up_window_sec,
+        min_acr: ws.min_acr,
         members: Array.from(ws.members.values()),
         tasks: Array.from(ws.tasks.values()),
         overrides: Array.from(ws.overrides.values()),
@@ -1882,6 +1921,7 @@ var Coordinator = class {
         handoffs: Array.from(ws.handoffs.values()),
         snapshots: Array.from(ws.snapshots.values()),
         route_decisions: Array.from(ws.route_decisions.values()),
+        idempotency_keys: ws.idempotency_keys,
         audit: ws.audit,
         chain_head: ws.chain_head,
         chain_enabled: ws.chain_enabled
@@ -1904,6 +1944,7 @@ var Coordinator = class {
         mode_ceiling: w.mode_ceiling ?? "production",
         routing_policy_uri: w.routing_policy_uri,
         step_up_window_sec: w.step_up_window_sec ?? 300,
+        min_acr: w.min_acr,
         members: /* @__PURE__ */ new Map(),
         tasks: /* @__PURE__ */ new Map(),
         overrides: /* @__PURE__ */ new Map(),
@@ -1912,6 +1953,7 @@ var Coordinator = class {
         handoffs: /* @__PURE__ */ new Map(),
         snapshots: /* @__PURE__ */ new Map(),
         route_decisions: /* @__PURE__ */ new Map(),
+        idempotency_keys: w.idempotency_keys ?? {},
         audit: w.audit ?? [],
         chain_head: w.chain_head,
         chain_enabled: !!w.chain_enabled
@@ -1950,6 +1992,16 @@ var Coordinator = class {
     if (this.options.requireSignatures && method !== "participant.join" && method !== "workspace.create") {
       const sigErr = this.verifySignature(envelope);
       if (sigErr) return reply(envelope, { error: sigErr });
+      if (method === "participant.rotate_key") {
+        const signingKid = envelope.sig.split(":")[1];
+        const oldKid = params.old_kid;
+        if (oldKid !== void 0 && signingKid !== oldKid) {
+          return reply(envelope, { error: rpcError(
+            E.SIG_ROTATION_KEY_MISMATCH,
+            "Rotation must be signed with the old key"
+          ) });
+        }
+      }
     }
     if (this.options.enforceStepUp && PRIVILEGED_METHODS.has(method)) {
       const stale = this.checkStepUp(params);
@@ -1980,6 +2032,16 @@ var Coordinator = class {
         }
       }
     }
+    if (method === "task.create") {
+      const wsId2 = params.workspace;
+      const ws = typeof wsId2 === "string" ? this.workspaces.get(wsId2) : void 0;
+      const key = params.idempotency_key;
+      if (ws && typeof key === "string") {
+        const existingId = ws.idempotency_keys[key];
+        const task = existingId ? ws.tasks.get(existingId) : void 0;
+        if (task) return reply(envelope, { result: { task_id: existingId, state: task.state } });
+      }
+    }
     const handler = this.handlers.get(method);
     if (!handler) {
       return reply(envelope, { error: rpcError(E.METHOD, `Unknown method: ${method}`) });
@@ -2093,7 +2155,13 @@ var Coordinator = class {
     const ws = this.workspaces.get(wsId);
     if (!ws) return null;
     const member = ws.members.get(sender);
-    if (!member || member.oidc_auth_time === void 0) return null;
+    if (!member) return null;
+    if (member.type !== "human" && member.oidc_sub === void 0) return null;
+    if (member.oidc_auth_time === void 0) {
+      return rpcError(E.OIDC_STEP_UP_REQUIRED, "Step-up authentication required", {
+        window_sec: ws.step_up_window_sec
+      });
+    }
     const nowSec = Math.floor(Date.now() / 1e3);
     const age = nowSec - member.oidc_auth_time;
     if (age > ws.step_up_window_sec) {
@@ -2102,6 +2170,12 @@ var Coordinator = class {
         age_sec: age
       });
     }
+    if (ws.min_acr !== void 0 && member.oidc_acr !== ws.min_acr) {
+      return rpcError(E.OIDC_STEP_UP_REQUIRED, "Step-up required: acr below the workspace minimum", {
+        required_acr: ws.min_acr,
+        acr: member.oidc_acr
+      });
+    }
     return null;
   }
   // ==========================================================
@@ -2151,6 +2225,7 @@ var Coordinator = class {
       mode_ceiling: p.mode_ceiling ?? "production",
       routing_policy_uri: p.routing_policy_uri,
       step_up_window_sec: typeof p.step_up_window_sec === "number" ? p.step_up_window_sec : 300,
+      min_acr: p.min_acr,
       members: /* @__PURE__ */ new Map(),
       tasks: /* @__PURE__ */ new Map(),
       overrides: /* @__PURE__ */ new Map(),
@@ -2159,6 +2234,7 @@ var Coordinator = class {
       handoffs: /* @__PURE__ */ new Map(),
       snapshots: /* @__PURE__ */ new Map(),
       route_decisions: /* @__PURE__ */ new Map(),
+      idempotency_keys: {},
       audit: [],
       chain_enabled: chainEnabled,
       chain_head: chainEnabled ? ZERO_HASH : void 0
@@ -2171,6 +2247,10 @@ var Coordinator = class {
     if (miss) return { error: rpcError(E.PARAMS, `Missing field: ${miss}`) };
     const ws = this.workspaces.get(p.workspace);
     if (!ws) return { error: rpcError(E.PARAMS, `Unknown workspace: ${p.workspace}`) };
+    if (this.options.requireReadMembership) {
+      const notMember = this.requireMember(ws, p.from);
+      if (notMember) return notMember;
+    }
     return { result: {
       id: ws.id,
       created: ws.created,
@@ -2188,10 +2268,15 @@ var Coordinator = class {
     } };
   }
   opWorkspaceSetProfiles(p) {
-    const miss = missing(p, ["workspace", "profiles"]);
+    const miss = missing(p, ["workspace", "from", "profiles"]);
     if (miss) return { error: rpcError(E.PARAMS, `Missing field: ${miss}`) };
     const ws = this.workspaces.get(p.workspace);
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
+    const notMember = this.requireMember(ws, p.from);
+    if (notMember) return notMember;
+    if (ws.members.get(p.from).role !== "admin") {
+      return { error: rpcError(E.NOT_AUTHORISED, "workspace.set_profiles requires the admin role") };
+    }
     const newProfiles = [...p.profiles];
     if (!newProfiles.some((pr) => pr.startsWith("core/"))) newProfiles.push("core/1.0");
     ws.profiles = newProfiles;
@@ -2229,6 +2314,7 @@ var Coordinator = class {
       member.oidc_sub = claims.sub;
       const at = claims.auth_time;
       if (typeof at === "number") member.oidc_auth_time = at;
+      member.oidc_acr = claims.acr;
       const cnf = claims.cnf;
       const cnfJwk = cnf?.jwk;
       if (cnfJwk && typeof cnfJwk.kid === "string") {
@@ -2257,6 +2343,7 @@ var Coordinator = class {
     if (existing) {
       if (member.oidc_sub !== void 0) existing.oidc_sub = member.oidc_sub;
       if (member.oidc_auth_time !== void 0) existing.oidc_auth_time = member.oidc_auth_time;
+      if (member.oidc_acr !== void 0) existing.oidc_acr = member.oidc_acr;
       if (member.vc_holder !== void 0) existing.vc_holder = member.vc_holder;
       for (const k of attested) {
         if (!existing.keys.some((x) => x.kid === k.kid)) existing.keys.push(k);
@@ -2277,6 +2364,8 @@ var Coordinator = class {
     if (miss) return { error: rpcError(E.PARAMS, `Missing field: ${miss}`) };
     const ws = this.workspaces.get(p.workspace);
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
+    const notMember = this.requireMember(ws, p.from);
+    if (notMember) return notMember;
     const assignee = p.assignee || p.to;
     if (!assignee || !ws.members.has(assignee)) {
       return { error: rpcError(E.PARAMS, "Assignee not in workspace") };
@@ -2311,11 +2400,14 @@ var Coordinator = class {
     if (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;
     return { result: { task_id: taskId, state: "created" } };
   }
   opTaskUpdate(p) {
     const ws = this.workspaces.get(p.workspace);
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
+    const notMember = this.requireMember(ws, p.from);
+    if (notMember) return notMember;
     const task = ws.tasks.get(p.task_id);
     if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
     const newState = p.state;
@@ -2358,6 +2450,10 @@ var Coordinator = class {
   opAuditRead(p) {
     const ws = this.workspaces.get(p.workspace);
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
+    if (this.options.requireReadMembership) {
+      const notMember = this.requireMember(ws, p.from);
+      if (notMember) return notMember;
+    }
     const range = p.range ?? {};
     const filter = p.filter ?? {};
     const fromSeq = range.from_seq ?? 0;
@@ -2394,12 +2490,38 @@ 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 (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: []
     };
@@ -2407,6 +2529,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}`) };
@@ -2423,6 +2576,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,
@@ -2457,6 +2612,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;