Repository navigation
v0.4.0-alpha.0
Pre-release
Pre-release
·
41 commits
to main
since this release
Added
melra setup --client claude-code --exclusivetakes Claude Code's own tools that change anything or reach the network away in its settings, for every session in the workspace: with--writeit merges a bare deny rule for each of a list pinned to Claude Code's tools reference (Bash,PowerShell,Monitor,Edit,Write,NotebookEdit,WebFetch,WebSearchand eight more) into the workspace's.claude/settings.local.jsonas a union, keeping every rule there, editing in place and saving the old file as.bak, and setsMELRA_HARNESS_TOOLS=1in the.mcp.jsonentry; a settings file that is not strict JSON, which Claude Code would not load, is refused.--managed <dir>instead stages amanaged-settings.json(the same list, plusallowManagedPermissionRulesOnly,allowManagedHooksOnlyandpermissions.disableBypassPermissionsMode) and amanaged-mcp.jsonlisting only melra, by absolute path, in<dir>, and prints thesudo installlines (on Windows, the destination) that put them where Claude Code reads managed settings, with each staged file's SHA-256. MELRA never writes that folder or runssudo; it refuses annpxmelra or a melra ornodeinside the home folder, a--managedfolder inside Claude Code's (in any letter case on macOS), and a staged file that differs.--dry-runprints the.mcp.jsonand settings files as they would be written and writes nothing, not even the default policy. Other clients are refused. See Claude Code's settings.melra doctorhas aharnessline, and its JSON aharnessobject, wherever Claude Code is in play: it reads the managed files at their platform path, the project's settings files and the user's, and reports each pinned tool as removed or present, each managed file's owner, mode and writability by this user, the lock keys set or missing, the serversmanaged-mcp.jsonlists and the executable its melra entry runs, admin-group membership and each file's SHA-256. It reads them as strict JSON, as Claude Code does. While claude.ai settings holding a policy rank above the managed files, it counts that policy's rules and locks in their place and names that file; undermanagedSourcesBehavior: "merge"it counts them together with the managed files without naming it. While an MDM profile it cannot read ranks above them on macOS, without merge, it counts no rule from any file and says so. It warns in either mode and never fails, and reports observations only.melra probe [--json], run inside an agent's box before the agent starts, reports whether the box stops what it should. It creates and removes a file in the workspace, opens the database and key inMELRA_HOME(set to the server's, as the box sees it) without reading them, makes a TCP connection to a public address (--public, default1.1.1.1:443) and to another local port (--local, default one it listens on itself), and starts the shell, and reports each asconfinedoropen. Only a refusal counts as confined; what it could not try is open,not tested. It then checks that the MELRA running outside the box answers on--socket(orMELRA_SOCKET) or a loopback--url, asking without a token; with none of the three it refuses to run (probe_endpoint_missing). It exits 0 only when every check is confined and MELRA answers. It sends nothing over its connections, changes no setting, and proves only the checks on its list. See checking an agent's box.examples/deploy/compose/compose.yamlruns MELRA and the agent in two containers, so the agent's only way to change the workspace or reach the network is MELRA's socket. MELRA serves--socketin enforced mode with the workspace read-write and its data in a volume of its own, on a volume that holds only the socket, with no port published. The agent gets the workspace read-only, no MELRA data, no credential but the token MELRA's socket asks for, and an internal network with no route out and, in gateway modeisolated(Docker Engine 28.0 or later), no address on the host, and runs as MELRA's user so the mode-0600socket admits it. Both run with a read-only root, no capabilities,no-new-privileges, and caps on processes and memory (pids_limit,mem_limit). From a checkout,docker compose -f examples/deploy/compose/compose.yaml upstarts it with a stand-in agent that runsmelra probe.pnpm compose:smoke, run in CI on Linux, checks it from the agent's side: the probe must find the workspace write, MELRA's database and key, and connections out and to the host refused, both aimed at a port on the runner so nothing leaves it, and a file write through the socket with the TypeScript SDK, approved withmelra approvein MELRA's container, must reachverified_successwith a receipt. Thedocker run -istdio recipe is now described as what it is: it boxes MELRA, not the agent, and is a developer-mode recipe. See MELRA and the agent in two containers.- An operator's deny says why:
melra approve <task-id> --denytakes--reason wrong_target|too_broad|not_now|never|other(otherwhen left out) and--note <text>, and the console's Deny takes a reason from a list and an optional note. The note holds up to 1,000 characters, is stored redacted and is never read by MELRA. Each deny is recorded once per challenge in a newapproval_denialstable with the approver, the channel (out_of_bandfrom an enforced process), the time, the render digest and a keyed digest of the operation, and the task it cancels gainsdenial(reason,note,channel,approver,decidedAt), whichmelra_task_statusreturns. A task its agent cancelled withmelra_task_cancelhas nodenial, so the two no longer leave the same record. Nothing acts on a denial yet. - Answers MELRA refuses for coming from the agent's side where only an operator answers, or for not matching what they answer, are now recorded (#424):
approval_in_band_refused(frommelra_execute,melra_workflow_advanceand theapproveharness tool),judgement_in_band_refused,workflow_input_in_band_refused,approval_action_digest_mismatch,approval_render_mismatch,approval_phrase_mismatchandapproval_id_mismatch. A newrefusalstable keeps the task or run, the code, the mode, the sender's declared principal and the client its transport authenticated, if any, and the time, and nothing that was sent. It keeps one row per task or run and code, the first, so sending the same answer again adds nothing. A refused verdict is recorded after the transaction it was refused in is rolled back. An approval sent withmelra workflow advance --approvalor a verdict sent withmelra judgeis not recorded, such asmelra judgewithout--mode enforcedon an enforced task; a decisionmelra approveor the console records that does not match is recorded under the approver's name.melra tasksandmelra statusshow how many are recorded and the latest five (refusalsin their JSON, inmelra tasks --jsononly when there are any),melra watchreports each new one, andmelra tasksmarks with!a task whose agent sent an approval or verdict only an operator gives; a run's show in the latest five. approval_denialsandrefusalsarrive in migration 8 and are append-only, as migration 7's tables are (record_append_only). Only this version writes them, so an older MELRA sharing the home keeps writing as it did.pnpm benchmark:aarmruns a self-check of MELRA against the 21 AARM v1.0 minimum tests (17 MUST, 4 SHOULD) through the real runtime, with no model and no network beyond loopback, in a few seconds. The cases are MELRA's own, as data inevals/src/aarm/corpus.ts; which cases map to which test, our paraphrase of each test and the sources (a hash of the aarm.dev table, never its text) are pre-registered inevals/manifests/aarm-v1.0-minimum-tests-v1.json, whose SHA-256 the harness pins and checks before it runs. A case needing an interface MELRA lacks (defer, modify, a record verifier, signed receipts, an audit export, sessions, labels), or whose steps are not written yet, is reportednot_implemented, never run. It writes an artifact only with--output <file>. It is a self-run mapping, not AARM conformance. Seedocs/research/AARM_SELFCHECK.md.wildcardMatch(value, pattern)in@melra/receipt-schema: the one*pattern match capability grants, credential delegations andurl_matchesshare, in time linear in its input.
Changed
- A task policy denies at planning now gets a
POLICY_BLOCKEDcertificate, as one denied at execute already did, and itscertificateIdnames it (#424). - Breaking: The console's deny route takes only
{ "reason", "note" }, both optional, where it ignored its body; any other body is refused with nothing recorded. - Breaking:
melra workflow advance --approvalnow sends as the operator and checksMELRA_APPROVERas--inputdoes, so a name it does not accept is refused before the run moves. - Breaking: the MELRA kernel is now licensed under the GNU Affero General Public License v3.0 only (
AGPL-3.0-only) instead of Apache-2.0, and XAGI Labs Private Limited also offers it under a commercial license. That covers@melra/cli,@melra/serverand every other package except the SDKs:@melra/sdk,@melra/protocoland themelraPython package stay Apache-2.0, as doexamples/and the code samples in the documentation, so code that only calls MELRA is unaffected. Releases up to and including0.3.0-alpha.22were Apache-2.0 and stay so. Contributions now need the Contributor License Agreement as well as a DCO sign-off, and the MELRA name and logo are covered by TRADEMARKS.md. The official logo and hero artwork are now all rights reserved instead of CC BY-ND 4.0; copies already distributed under it keep that license. Each published package now ships its ownLICENSE, and the release archive, container image and single executables carryLICENSEandNOTICE. LICENSING.md maps each path to its license.
Security
- An agent's attempt, in enforced mode, to approve its own change, answer its own semantic question or answer a question meant for an operator is now recorded where the operator looks, not only refused. Each such record is bounded, so repeating an attempt cannot grow the store.
- Matching URL and host patterns and redacting secrets, in text and in a command's arguments, now take time linear in their input, so a crafted value cannot stall MELRA. Grants, credential delegations and
url_matchesanswer as before, and redaction takes out the same text.