Skip to content

CHAP 0.3.5: who decides, who joins, and CHAP you can run

Latest

Choose a tag to compare

@brightbeamarsalan brightbeamarsalan released this 08 Nov 18:49

The protocol packages move together to 0.3.5, and two packages join them:
@brightbeamai/chap-server, the desk server, and
@brightbeamai/chap-code-gate, the code gate, both taken out of the
generated projects so an upgrade reaches them. chap-analytics 0.2.6, on
its own track, reads what 0.3.5 records.

Most of the coordinator changes close ways a review could be settled by
someone other than an independent person, or a member could join under a
name or a role nobody gave it. They change what the specification
requires, which would make a minor release; as security fixes they ship as
a patch release on the supported 0.3 line, as SECURITY.md sets out and as
0.3.4 did. Many refuse calls 0.3.4 accepted: "Upgrading" below lists each
one and what to send in its place.

npm install @brightbeamai/chap-coordinator@0.3.5
pip install "chap-coordinator[crypto]==0.3.5" "chap-analytics==0.2.6"
npx create-chap-app@0.3.5 upgrade my-project

The security advisories
give the details of each security fix, and
CHANGELOG.md
has this entry in full.

Security

  • A review a task requires is opened by its work, and decided by
    people.
    On a task that requires review, the review opens only on
    task.complete, from the assignee, under the workspace's
    review_rule; review.request only adds people to a review already
    open, and before it opens is refused with -32011, whoever sends it.
    Only type: "human" members decide it, and a reviewer set the
    coordinator picks holds only people.
  • The authors of the work do not decide its review. The assignee and
    the member that completed the work are recorded as the review's
    authors, and a decide.*, abstain.declare or review.acknowledge
    from one of them is refused with -32011, however the review is
    addressed. The authors go with the work: a new round keeps the earlier
    rounds' authors, a task escalate.raise or control.supersede makes
    carries the authors of the task it replaces as prior_authors, and a
    task task.route or handoff.accept moves keeps there the member it
    leaves, where that member moved it on itself. A member another member
    passed the task to stays a reviewer, so nobody can leave a person out of
    a review by routing the work through them. A reviewer's decision that
    completed a task, or a route of a completed task, is not taken for a
    completion of the work.
  • Its authors do not end a review. Only an author takes the work back
    to revise it; a task under review is not declined before a reviewer
    rejects it; escalate.raise hands the review on with the work; and from
    the moment a required review opens until a reviewer rejects the round,
    its authors cannot end the task with control.cancel,
    control.supersede, or a pause and then task.update to cancelled,
    under review or after taking the work back, nor end a successor an
    escalation or a supersede makes, which nobody declines either. A task
    that has held a review completes only through a decision: completing it
    again opens a new round.
  • A workspace sets its review rule. workspace.create takes
    review_rule (any_one_approves, all_approve or quorum:<n>), so a
    deployment can ask for more than one approval and no author can ask
    for fewer.
  • A signed request takes effect once. A signed call identical to one
    already accepted is refused with -32075 and data.accepted_at_seq, so
    an accepted envelope copied from the log cannot be sent again, a
    reviewer's reject replayed against a resubmitted artefact for instance.
  • Who signs. A workspace's signature_policy is "all", the default,
    or "humans": under "humans" an agent member may call unsigned, and
    people and services sign. A workspace that advertises
    security-signed/1.0 or an identity profile cannot drop it with
    workspace.set_profiles, nor advertise one the coordinator does not
    enforce.
  • The admin role is granted. role: "admin" at participant.join is
    accepted from the workspace's first member, or from a participant an
    admin's invitation names as admin, and is otherwise refused with
    -32011. workspace.invite is built, and join_policy: "invite"
    admits only invited participants and the first member. Where a token or
    credential verifier is configured, an invitation names no keys for a
    person, a member or not: their keys arrive with the token or
    presentation they join with.
  • Joins. A join under a member's name with keys the member does not
    hold is refused with -32011; a new key arrives through
    participant.rotate_key, under a kid of its own. Where signatures are
    required, a join with no key is refused with -32602. A URI's scheme
    must match its type, and group: and workspace: addresses cannot
    join. Where a token verifier is configured, a person joins with a token
    for them (-32403 without one) that names them, and a token that
    carries cnf.jwk or a nonce binds the join's keys to that key (-32404
    otherwise). A token or presentation sent at join is kept as its SHA-256
    digest.
  • The first join of a person needs the server's code. Where signatures
    are required and nobody signs in at an identity provider, a desk server,
    Node or Python, refuses the first join of a person chap.config.json
    names without the enrolment code it prints at start, so a program that
    cannot read the server's console or the project's data/ cannot take a
    person's name before they open the desk. The desk takes the code from
    the link the server prints, or asks for it; "enrolment": false turns
    it off. The code gate's commands, which an agent runs, print no code.
    Against a program running as the person's own user, a coding agent with
    a shell among them, the code is no boundary: the code gate's trust
    policy, which pins the reviewers' keys, is.
  • Where people sign in. Where people sign in at an identity provider,
    the Node desk server starts only where every call is signed, the
    agent's among them, since it is then reached from other machines; its
    read API and analytics pages answer a person signed in at the desk, or
    a member whose key signs the read. The production template signs every
    call.
  • Signatures have one spelling. An Ed25519 signature in anything other
    than canonical standard base64 is refused.
  • A pause holds. A paused participant can neither lift its own pause
    nor leave and join again to come back unpaused.
  • Smaller fixes. handoff.accept takes only tasks the proposer still
    holds. __proto__, constructor and prototype are refused as
    idempotency keys. A -32603 answer carries no exception text; the
    TypeScript coordinator passes the error to onInternalError. Both
    coordinators keep auth_time in whole seconds, and none past 2^53.
  • The servers. The reference servers and the desk servers check
    Host and Origin, take JSON only, and send no
    Access-Control-Allow-Origin. A desk server admits to its workspace
    only the members chap.config.json names. The desk sends a strict
    Content-Security-Policy and refuses framing, runs analytics in a
    sandbox, keeps a reviewer's key where no script can read it, and marks
    invisible characters and characters outside ASCII in names and changed
    lines. A server error answers with no exception text, and the Node desk
    server answers a request target that is no URL path with 400.
  • The code gate's hooks. The hooks read the gate's address and the
    signature rule from chap.config.json alone, fail closed, and chain to
    the repository's own hooks. A gate joins the trust policy's reviewers
    with their pinned keys at start, so nobody can take their names first.
  • MCP and A2A act as an agent. The MCP and A2A commands act as
    agent:assistant by default, with --as to name another agent, and the
    libraries refuse a person as the participant they act as. The MCP
    commands offer the agent's tools, and the A2A executors the agent's
    skills, unless told to offer every one.

Added

  • @brightbeamai/chap-server. The desk server for Node http, Express
    or Fastify, mounted at any prefix: the desk, /chap, /mcp and the read
    API. The desk signs with a passkey where the browser has one, records
    review.acknowledge when a reviewer opens a review, and notifies people
    through a webhook or the console when a review or a question waits.
    Production projects sign people in with OIDC, with PKCE, and bind the
    token to the desk's key. signedRead in its client signs a read with a
    member's key.
  • @brightbeamai/chap-code-gate. The code gate's commands, hooks and
    verifier as a package, with chap-code-gate on the path.
  • The Python package runs CHAP. chap-coordinator serve runs the desk
    server, chap-coordinator mcp the MCP server over stdio, and
    chap-coordinator a2a the A2A server. chap_coordinator.client has
    HttpCoordinator, Participant and Signer, and
    chap_coordinator.server the desk server as an ASGI app.
  • review.acknowledge. A reviewer says they have opened a review, so
    the time a review waits unopened is told apart from the time it is read.
  • WebAuthn signatures. A webauthn: tag carries a passkey's
    assertion, verified against the origins its key lists.
  • create-chap-app upgrade and add. upgrade brings a generated
    project forward, the copies a project made of the server and the gate
    included, and adds the configuration the template's code needs, such as
    outbound-approval's operator. --adopt-settings takes the template's
    settings and moves the store aside where they change signing or the
    chain. add puts CHAP into a project that exists. Each project is
    stamped with its template and release.
  • MCP 2026-07-28. chapMcpHttpHandler serves MCP over HTTP, answering
    2026-07-28 beside the handshake versions. chap-mcp-server --url
    forwards to a desk.
  • A2A 1.0. @brightbeamai/chap-coordinator-a2a runs on @a2a-js/sdk
    1.3 and keeps answering 0.3 clients. A call the coordinator refuses ends
    the task as failed. The Python a2a extra installs a2a-sdk with its
    HTTP server.
  • The framework bridges wait for a person. Each bridge opens the
    review and waits for the decision made in the desk, through
    chap_coordinator.bridge. chap-langgraph opens the review in one node
    and decides in the next, chap-ag2 supports AG2 0.x and approves AG2
    1.x tool calls, and chap-google-adk runs the reviewer's edit. A
    decision a bridge records from another interface carries
    via: "bridge-record".

Changed

  • Node.js 22 or later. Node 20 reached its end of life on 30 April
    2026. CI tests Node 22, 24 and 26, and the images run Node 24 as a
    non-root user.
  • Defaults in a new project. The store is the project's own, the
    evidence chain is on, and require_signatures takes "humans", under
    which the agent works unsigned and every person signs; the production
    template keeps true, under which the agent signs too.
  • Ports. The mcp-gate template and the Python desk server listen on
    8792, clear of a port some editors use for their own sign-in.
  • The store. A coordinator reads what another process wrote before it
    answers. By default, a write that fails or meets a newer one is answered
    with -32603 and data.reason: "store": the call took no effect, and
    the caller may send it again. The TypeScript coordinator opens SQLite
    through node:sqlite, on Node 22.13 and later, where better-sqlite3
    is not installed.

Upgrading

Upgrade every coordinator, then every generated project with
npx create-chap-app@latest upgrade and the project's directory. A
project keeps its settings; --adopt-settings takes the template's on a
new store, since a store's workspace keeps the settings it was created
with. Calls 0.3.4 accepted that 0.3.5 refuses, and what to do instead:

  • Opening a review a task requires. review.request on such a task
    from anyone, unless it adds people to the open review: call
    task.complete from the assignee, and set the rule with review_rule
    at workspace.create. A code gate configured with quorum:<n> or
    all_approve refuses to propose on a store created under a weaker rule;
    start it on a new store. On such a task, too: a task.complete from
    anyone but the assignee, and a review.request naming an author, a
    member who is not a person, or a group: or workspace: scope.
  • Deciding. A decision, abstention or acknowledgement from an author
    of the work, a member the task was routed, handed, escalated or
    superseded from among them, and a decision from an agent or a service on
    a review a task requires.
  • Ending a review with no decision. task.update back to
    in_progress from anyone but an author; task.update to declined
    before a reviewer rejects the work, or to completed on a task that
    holds a review; and, from an author of a required review until a
    reviewer rejects the round, control.cancel, control.supersede, and
    task.update from paused to cancelled, the work taken back or not, on
    the task or on a successor that carries its review; and task.update to
    declined of such a successor, from anyone. A task that has held a
    review and is completed again opens a new round; it no longer completes.
  • Roles and profiles. role: "admin" at join from anyone other than
    the first member or an invited admin: invite admins with
    workspace.invite. workspace.set_profiles that drops
    security-signed/1.0 or an identity profile, or adds one the
    coordinator does not enforce.
  • Joins. A join with keys other than the member's (rotate instead), a
    keyless join where signatures are required, a URI whose scheme is not
    its type, a join as a group: or workspace: address, and a person's
    join with no token, or a token that does not name them or bind their
    key, where a verifier is configured. At a desk server, a join under a
    name chap.config.json does not give, and a person's first join
    without the enrolment code.
  • Signatures. An unsigned call from a person or a service under
    "humans", a signed call sent twice, an Ed25519 signature in
    non-canonical base64, and a participant.rotate_key to a kid the
    member holds.
  • Pauses. A paused participant's control.resume of its own pause,
    and its participant.leave.
  • Invitations. workspace.invite naming keys for a person where a
    token or credential verifier is configured.
  • Transports. The MCP and A2A commands act as agent:assistant, with
    the agent's tools or skills, unless --as, --tools all or
    --skills all says otherwise, and the libraries refuse a person as the
    participant they act as: a client that recorded people's decisions
    through MCP needs the desk, or another signing path, for them.
    @brightbeamai/chap-coordinator-a2a needs @a2a-js/sdk 1.3, and the
    Python a2a extra installs a2a-sdk[http-server].
  • Where people sign in. A Node desk server configured to sign people
    in at an identity provider no longer starts under "require_signatures": "humans" or off, or on a store created under either or before it signed
    people in: set true, and start a new store by moving the old one aside;
    create-chap-app upgrade --adopt-settings does both where it changes the
    setting.
    A read of its API from anyone but a signed-in person or a member whose
    key signs it (signedRead).
  • Node.js. Node 20.

chap-analytics 0.2.6

Reads the logs of chap-coordinator 0.3.5.

Added

  • Time to open and time to decide. Coordinators from 0.3.5 record
    review.acknowledge when a reviewer opens a review. The decisions table
    gains acknowledged_at, time_to_open_s and time_to_decide_s, and
    stats.latency splits each pass's wait the same way, open passes
    included; open_queue says which waiting reviews were opened. The
    latency brief reports both medians, counts the waiting reviews nobody
    has opened, and says to tell reviewers when a review arrives where most
    of the wait comes before anyone opens the work. A log without
    acknowledgements reads as before.
  • Decisions a bridge recorded. A framework bridge records a decision a
    person made outside CHAP, and from 0.3.5 the call carries
    via: "bridge-record". The decisions table and each pass in
    stats.latency carry via; latency_by, survival and the latency
    brief leave out passes a recorded decision settled, and the brief counts
    them. It also points out decisions made within a second of their request,
    which a bridge from before 0.3.5 records unmarked.
  • The artefact each decision was made on. The decisions table gains
    artefact.

Fixed

  • A completion after a review. From 0.3.5 a task that has held a review
    completes only through a decision, and completing it again opens a new
    pass. The replay read such a completion as the end of the task, so the
    decision that followed landed in the earlier pass. It now holds the
    completion and opens a pass when a decision or an acknowledgement on the
    task follows, or when the state shows the task under review; a log from
    before 0.3.5 reads as before.
  • The successor of an escalated task. From 0.3.5 escalate.raise
    hands a review on with the work: the successor requires review when the
    original held one. The replay now reads it so.
  • Approved evaluation cases. export.evaluation_cases(include_approved=True)
    gave approved tasks an empty agent_output and corrected_output. Both
    now hold the artefact the settling decision approved.
  • One reviewer. The concentration brief said reviewing was spread across
    people when one reviewer decided everything on a small sample, and wrote
    "1 reviewers". One reviewer is now named as the only one, and a high
    share on too few decisions says the sample is too small to tell.