MCP access gates: claim values, read/write split, ported hardening

[flic]

Ports the access-gate work that node-red-contrib-mcp-server gained after it was extracted from
hal2, and adds a read/write split for hal2's own built-in tool catalog. Until now a token that
could read device state could also switch every light in the house — the only per-tool distinction
that existed was MCP_ADMIN_TOOL_NAMES.

Access model

One claim name on the Event handler carries three comma-separated any-of value lists,
combined with AND:

Gate	Covers	Default
Read tools	get_all_states, get_state, get_history, get_scenes, get_presence, get_alerts, analyze_patterns	empty — any authenticated caller
Write tools	set_light, control_device, control_fan, control_cover, control_spa, control_climate, activate_scene	empty — same as read
Admin tools	get_flow, deploy_flow	admin

The read list is the floor; writes are checked on top of it, so read = family / write = ops
lets the household see everything while only ops can change anything. All new fields default to
empty, which is no constraint, so an existing install behaves exactly as before.

Tools a caller cannot use are absent from tools/list and from the initialize blurb rather than
advertised and then refused. A direct call to a hidden tool returns an MCP tool result with
isError: true and a readable reason, so the model is told why instead of getting a generic
"tool execution failed".

Three findings that shaped it

• control_light is an undocumented alias of set_light that the dispatcher accepts but the
  catalog does not list. A write gate keyed on a name set has to include it or it is a clean
  bypass. Pinned by its own test.
• Read/write cannot be derived from dispatcher membership — get_scenes and get_alerts live
  in dispatchControlTools but only observe. The classification is an explicit set.
• A tool in neither set is treated as a write, so a future addition that nobody classifies
  fails closed instead of slipping through ungated.

Scope decision: MCP only

Gates are enforced on the MCP surface, where claims are cryptographically verified. hal2Api
reads msg.claims straight off the message, which any flow can set, so gating it would be
decoration rather than a boundary; it keeps its own local Allow admin tools checkbox. The gate
therefore travels in opts through node.callTool — the single choke point both surfaces reach —
rather than being derived from the claims.

Ported verbatim

lib/claim-gate.js and lib/mcp-rpc.js are byte-identical to their upstream copies, which is
what keeps future fixes a cp away in either direction. The standalone hal2MCPServer route is
rewired onto handleRpc, replacing ~90 lines of inline dispatch. The embedded /mcp route keeps
its own dispatch deliberately: its static, hardware-filtered catalog does not fit handleRpc's
registry shape, and generalizing it would end the byte-identical portability.

claimSatisfied is deleted now that both callers use createToolGate.

Nested claim paths: a dotted claim name such as realm_access.roles is walked as a path when
no literal key of that name exists, so Keycloak-style nested roles work. A literal key always
wins, so PocketID's flat groups is untouched.

Hardening

• Object.create(null) for the tool registry and pending-call map. Caller-supplied names like
  __proto__ previously resolved through the prototype chain, past the "Unknown tool" check, into
  a 30-second hang.
• Duplicate tool-name warning at registration; ownership-checked unregisterMCPTool.
• Owner-tagged route removal, so partial-deploying one of two servers sharing a path no longer
  strips its sibling's route.
• Configurable localDebugGroups — mcp-auth already accepted it but nothing supplied it, so the
  debug token was permanently admin and the gates could not be exercised locally.

Editor and docs

The claim field moved out of the admin section, which is hidden whenever admin tools are off — the
read/write gates need the same claim. hal2MCPIn gained a per-tool list with a live tip that reads
the selected server's actual claim name. docs/API.md now tags every tool read/write/admin.

Testing

183 passing, up from 175 — including 19 borrowed claim-gate tests, 21 borrowed RPC-dispatcher
tests with the prototype-chain regression, and 10 new gate-policy tests covering the
control_light alias, unknown-tool-is-write, and empty defaults reaching everything.

Verified live against the running instance: routes register cleanly, the embedded endpoint and the
standalone server both answer real OAuth-authenticated calls after the rewire, and a read-only
token is correctly refused write tools while keeping get_scenes/get_alerts.