feat(m0.6-r3): generic external CLI Tool Protocol v1
- add tool install/list/remove and unknown-command dispatch without hardcoded tool names or clap variants - validate and copy local tool packages atomically, reject entrypoint escapes and symlinks, record and re-verify SHA-256 - forward OsString args, stdio, cwd and exit status without a shell; never execute PATH programs implicitly - add black-box tests for arbitrary names, Unicode args, built-in conflicts, traversal, version mismatch, tampering and PATH hijacking - add ADR-0013 and mark R3 complete
This commit is contained in:
1 parent
7797d78d86
commit
25a1faa6ef
7 files changed
+859
-3
No files matched your search
+1
-1
@@ -42,7 +42,7 @@ providers).
|
||||
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
|
||||
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
|
||||
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending |
|
||||
| R3 Tool Protocol | Not started | — |
|
||||
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
|
||||
| R4 Analysis/Trace v1 | Not started | — |
|
||||
| R5 environment/isolation | Not started | — |
|
||||
| R6 release/consumers | Not started | — |
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# ADR-0013: Generic external CLI Tool Protocol v1
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-20
|
||||
|
||||
## Context
|
||||
|
||||
M0.6 must let external tools (`view`, `knowledge`, `prove`, or arbitrary
|
||||
third-party programs) become `marqdo <command>` entries without changing the
|
||||
core source or command enum. The CLI currently has a closed `clap` enum and no
|
||||
generic distribution path. C ABI plugins and foreign kernels are unrelated
|
||||
trust models: a Tool is a user-invoked native process.
|
||||
|
||||
## Decision
|
||||
|
||||
`spec/tool-v1.md` is implemented as follows:
|
||||
|
||||
* new top-level commands are limited to
|
||||
`tool install/list/remove` plus fallback for unknown top-level commands;
|
||||
* `tool.json` (schema `marqdo.cli-tool`, schema_version 1) declares
|
||||
`name`, `version`, `command`, `entrypoint` and optional compatibility; the
|
||||
core does not contain any tool name, download URL or business argument;
|
||||
* install requires a local manifest, validates the command (lowercase ASCII,
|
||||
no built-in conflict), rejects absolute/`..`/symlink-escaping entrypoints,
|
||||
copies the package without following symlinks into a user-controlled tool
|
||||
home, re-verifies the executable SHA-256, writes a registry record, and
|
||||
publishes atomically via rename;
|
||||
* dispatch checks the registry record, re-verifies the executable hash, starts
|
||||
the entrypoint directly with `OsString` arguments (no shell), inherits
|
||||
stdin/stdout/stderr and cwd, sets `MARQDO_BIN`/`MARQDO_TOOL_PROTOCOL=1`, and
|
||||
propagates the exit code;
|
||||
* a missing registration is an unknown command; a `marqdo-<name>` on PATH is
|
||||
never executed implicitly;
|
||||
* uninstall removes only the exact controlled installation directory.
|
||||
|
||||
The tool home defaults to the platform config directory and can be redirected
|
||||
with `MARQDO_TOOL_HOME` for tests/enterprise deployment.
|
||||
|
||||
## Alternatives
|
||||
|
||||
1. Add a `clap` variant per known tool. Rejected by the audit (E01/E12).
|
||||
2. Auto-discover `marqdo-*` from PATH (Cargo-style). Rejected: implicit
|
||||
execution and PATH hijacking; M0.6 requires explicit installation.
|
||||
3. Use the C ABI plugin registry. Rejected: different lifecycle, protocol and
|
||||
security boundary.
|
||||
4. Implement a remote registry first. Rejected: local manifest installation is
|
||||
the required closed loop; name-based installs are a future optional index.
|
||||
|
||||
## Compatibility
|
||||
|
||||
This adds one new top-level command (`tool`) and an unknown-command fallback.
|
||||
Built-in commands always win. Future core commands that collide with an
|
||||
installed tool are a breaking change and need an ADR/migration policy. The
|
||||
manifest is versioned; unknown optional fields are ignored in v1 but never
|
||||
imply authorization.
|
||||
|
||||
## Security
|
||||
|
||||
A Tool is a normal process run as the user, not inside the `.mq.md` sandbox.
|
||||
It does not automatically receive Marqdo capabilities, secrets or plugin
|
||||
handles. Install never runs the tool. The executable hash detects post-install
|
||||
tampering, not a malicious publisher; local source selection is the trust
|
||||
decision. Symlinks are rejected during package copy.
|
||||
|
||||
## Testing
|
||||
|
||||
`crates/cli/tests/tool_protocol.rs` covers arbitrary command names,
|
||||
install/list/remove, argument/exit-code forwarding, Unicode args, built-in
|
||||
conflict, traversal, version mismatch, binary tampering and PATH hijacking.
|
||||
`spec/tool-v1.md` lists the full black-box matrix.
|
||||
|
||||
## Migration & rollout
|
||||
|
||||
R3 adds the command surface. R4 can expose Analysis/Trace compatibility through
|
||||
the manifest's optional fields; no tool business logic enters the core.
|
||||
@@ -18,7 +18,7 @@ marqdo-cli/
|
||||
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6
|
||||
│ ├── STATUS.md implementation matrix (P0–P7)
|
||||
│ ├── contributor-guide.md this file
|
||||
│ └── adr/0001..0012-*.md accepted decisions
|
||||
│ └── adr/0001..0014-*.md accepted decisions
|
||||
├── spec/
|
||||
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
|
||||
│ ├── mapping.md AST → program roles
|
||||
|
||||
Reference in new issue
Block a user