claudemesh/.artifacts/specs/2026-05-04-session-capabilities.md

Session capabilities — first-class concept

Status: spec, queued behind v0.3.0 topic-encryption work. Owner: alezmad Author: Claude (Sprint B follow-up, 2026-05-04) Related: 2026-04-15-per-peer-capabilities.md (existing per-peer caps system, member-keyed), 2026-05-04-per-session-presence.md (per-launch session presence — what we're now restricting).

Problem

Per-peer capability grants (apps/broker/src/index.ts:2178+, 2309+) are keyed on the sender's stable member pubkey. The grant model gives the recipient fine-grained control: "alice can DM me", "bob can read state but not broadcast", etc.

But: as of v1.30.0 (per-session-presence), every claudemesh launch mints a per-launch ephemeral keypair with a parent attestation binding it to the member identity. The launched session inherits all the member's capabilities transitively, because cap enforcement always falls through to the member key.

Concretely:

• Member alice is in mesh flexicar, granted dm + state-read + state-write by everyone.
• Alice launches a session with claudemesh launch to do an automated task — say, run a Claude Code agent that iterates over PRs.
• That session has full member privileges. It can DM peers, write shared state keys (e.g. clobber current-pr), grant new caps, ban members, etc. — none of which the user wanted to delegate.

There is no way to express "this session can DM peers but cannot deploy services or grant caps." The parent attestation is a binary existence proof — "this session was vouched by a member" — with no capability subset.

Plus an adjacent footgun: set_state (apps/broker/src/index.ts:2949) has no cap check at all. Anyone in the mesh can write any key. The spec at 2026-04-15-per-peer-capabilities.md lists state-write as a planned cap but it was never wired into the broker. Shared keys like current-pr are write-anyone today.

Goal

A launched session can be issued a capability subset of its parent member, signed by the parent at launch time, and the broker enforces the intersection of recipient grants × session caps on every protected operation.

Non-goals

• Changing the existing per-peer cap model. Member-keyed grants stay authoritative for "who is allowed to talk to me."
• Cross-machine session caps (waiting on 2.0.0 HKDF identity).
• Per-tool granularity inside the Claude Code MCP surface — this spec only covers the broker-enforceable verbs (dm, broadcast, state-read, state-write, grant, kick, ban, profile-write, service-deploy).
• Delegation: a session cannot re-vouch a sub-session with its own cap subset. Only members can attest sessions. (Could be lifted in a future spec; today's launch flow doesn't need it.)

Design

Capability vocabulary

Existing (today, member-level):

Capability	Effect when GRANTED on a recipient → sender pair
read	Sender appears in recipient's list_peers
dm	Sender can DM recipient
broadcast	Sender's broadcasts reach recipient
state-read	Sender can read shared state
state-write	(planned) Sender can write shared state
file-read	Sender can fetch files recipient shared

New (session-level — cap subset on the attestation):

These are the verbs the session is allowed to invoke, NOT what peers can do TO it. A session attestation declaring ["dm", "read"] means the session can SEND dm/read-list operations; it cannot broadcast, write state, grant, etc.

Session cap	Gates which broker operations
dm	send with single recipient
broadcast	send with *, @group, #topic
state-read	get_state, list_state
state-write	set_state
grant	grant, revoke, block
kick	kick, disconnect
ban	ban, unban
profile-write	set_profile, set_summary, set_status
service-deploy	mesh_service_register, _unregister

The default cap set when no subset is declared: the full member set (today's behavior — opt-in restriction, not breaking).

Attestation v2

Existing v1 (apps/cli/src/services/broker/session-hello-sig.ts):

canonical = `claudemesh-session-attest|<parent>|<session>|<expires>`

New v2 (additive — broker accepts both):

canonical = `claudemesh-session-attest-v2|<parent>|<session>|<expires>|<sorted-caps-csv>`

Where <sorted-caps-csv> is the lower-cased, comma-joined, ASCII-sorted cap list. Empty-list = full member caps (default, back-compat).

Wire shape additions on session_hello:

{
  type: "session_hello",
  ...existing fields...,
  parentAttestation: {
    sessionPubkey,
    parentMemberPubkey,
    expiresAt,
    signature,
    // NEW:
    allowed_caps?: string[],  // omitted = full member set
    version?: 2,              // omitted = v1
  },
}

The broker version-detects: version === 2 → verify v2 canonical including allowed_caps. Default behavior is unchanged for clients that don't pass it.

Enforcement

Add allowed_caps: string[] | null to the in-memory PeerConn shape (apps/broker/src/index.ts:131). Populated from handleSessionHello (the v2 attestation supplies it) and from handleHello (control-plane / member connection — set to null, meaning "full member caps").

Effective cap check for a sending peer needing cap:

function senderHasCap(conn: PeerConn, cap: string): boolean {
  if (conn.allowed_caps === null) return true; // member-level, no subset
  return conn.allowed_caps.includes(cap);
}

Wire this into every broker operation in the table above. The existing per-peer recipient-cap check at 2178+, 2309+ stays — session caps gate the sender side, recipient grants gate the receive side, and both must allow:

allowed = senderHasCap(conn, capNeeded) && recipientGrants[sender][capNeeded]

set_state gate (bonus, ship together)

Today: no cap check. After this spec: set_state requires state-write on the sender side. Migration: existing members default to having state-write in their member caps (no recipient grant model for state-write — it's a sender-side gate only, mesh- wide). New attestations can omit it to forbid the session.

The recipient-side analog (per-peer state-write grants) is left for a future spec — today the value of guarding state-write is session-level (avoid an automated session clobbering shared keys), not peer-level.

CLI surface

claudemesh launch --caps dm,read         # tight: read-only chat agent
claudemesh launch --caps dm,broadcast    # send-only, no state writes
claudemesh launch                        # default: full member caps

claudemesh launch --caps ? prints the table above with descriptions.

claudemesh peer list --json includes allowed_caps per row when present (null = full member). Lets users audit what their running sessions can actually do.

Migration plan (mirrors 2026-04-15-per-peer-capabilities.md §"Migration plan")

1. Broker schema additive — PeerConn.allowed_caps in-memory only; no DB column. Reload-on-reconnect is fine because the attestation is re-sent on every WS open (it's the proof of identity).

2. CLI ships v2 attestation alongside v1. New --caps flag defaults to omitted (= v1 attestation, full caps). Older brokers ignore the new fields entirely.

3. Broker accepts v2. When allowed_caps arrives, store it. No enforcement yet — log denied operations as cap_check_dryrun metric counter, still allow them through.

4. Dry-run release. Ship one CLI + broker release that emits the metric but doesn't enforce. Watch for false positives in real meshes for ≥ 1 week.

5. Flip enforcement on. Broker rejects operations failing the cap check with forbidden: missing session capability "<cap>". Default ("no caps declared = full member") keeps existing sessions unaffected.

6. set_state gate ships in step 5 alongside the rest. Default member caps include state-write, so flipping it on doesn't break existing flows. Only sessions that explicitly omit state-write from --caps lose write access.

Crypto notes

• v2 attestation re-uses crypto_sign_detached over the new canonical string; same parent member secret key, same TTL caps (≤24 h), same expiresAt semantics.
• v1 signatures are NOT v2 signatures — collision is impossible because the canonical strings have different prefixes (claudemesh-session-attest vs claudemesh-session-attest-v2). Domain separation is intrinsic.
• Like the existing per-peer cap system: caps are server-enforced metadata, not capability tokens. A malicious broker can ignore them. This is about UX trust + footgun prevention, not protocol- level security.

Open questions

1. Should the session attestation also bind to a fingerprint of the launched binary / Claude version? Would let a member say "this session is constrained to Claude Code v1.34.15" so a compromised launched-binary doesn't get reused. Probably no — too much friction for the threat model.

2. What's the right default for claudemesh launch going forward? Once enforcement ships, do we change the default --caps from "full member" to "dm + read + state-read"? Tighter but breaks existing automation that writes state. Probably worth a one- release deprecation warning ("your session will lose state-write in v2.0.0 unless you pass --caps state-write") and then flip in v2.0.0.

3. Does --caps belong in ~/.claudemesh/config.json per-mesh defaults too? A user who always launches read-only agents wants caps: ["dm", "read"] as a personal default. Easy add; defer until users ask for it.

4. Per-tool MCP cap surface? Out of scope here, but: a claudemesh launch --tools peer:read,memory:write would be a finer cut than broker-verb caps. The broker can't enforce that — it'd live in the MCP wrapper / Claude Code's allowedTools. Different layer.

Test plan

• Pure-logic tests on senderHasCap (member-level → always true, empty caps → always false, declared caps → exact match).
• Broker integration: launch a session with --caps dm, attempt set_state → expect forbidden: missing session capability "state-write".
• v1 attestation still accepted, no allowed_caps set, all caps permitted (back-compat).
• v2 attestation with empty allowed_caps array → broker treats as "explicitly empty, no caps allowed" (NOT "full member"). The full-member default is "field omitted entirely". Test both.
• Dry-run mode: cap fail increments the counter but the operation proceeds. Smoke-test before flipping enforcement.

Estimate

• Spec review + open-question resolution: 1–2 days.
• Broker change (PeerConn field, attestation v2 accept, per-verb enforcement, dry-run mode): 2–3 days.
• CLI change (--caps flag, attestation builder, peer list surface): 1 day.
• Tests: 1 day.
• Dry-run release window: ≥ 1 week.

Total: ~1 sprint of focused work, plus a dry-run window.