clinkx 1.1.0 → 1.1.2

package/docs/security.md

@@ -0,0 +1,293 @@
+# ClinkX Security Model
+
+## Core Principle
+
+**ClinkX validates what goes IN, not what the CLI does.**
+
+ClinkX validates and constrains the *inputs* it accepts — file paths, arguments, environment variables. It does **not** sandbox the spawned CLI process. The subprocess runs with the full permissions of the user who started the ClinkX server.
+
+## What ClinkX Secures (Input Validation)
+
+### Allow-roots path validation
+
+- `CLINKX_ALLOWED_ROOTS` (comma-separated, default: `process.cwd()`) defines which filesystem paths the tool will accept as `absolute_file_paths` or `images` inputs.
+- All paths are resolved via `realpath` — symlink escapes are blocked.
+- Startup refuses to run from filesystem root (`/` or drive root) unless `CLINKX_ALLOWED_ROOTS` is explicitly set.
+
+### Context builder validation
+
+- `context_builder` accepts only roots under the current allowed roots and verifies real paths before reading.
+- Requests must include a bounded anchor: a `focus_paths` entry or nonblank `search_terms` entry. `include_globs` only narrows scanning when combined with those anchors and does not select context by itself. A root directory by itself is not enough.
+- Symlink escapes, broad/symlinked runs directories, parent traversal, and artifact-only runs directories are rejected or omitted.
+- High-confidence secret paths and content are omitted before preview, search, slice, bundle, or manifest artifacts are written **only when `allow_secrets:false`**. The secret filter is non-blocking and default-on (`allow_secrets:true`) — see "Context builder secret material" below.
+- `context_builder` is the only context-curation/filesystem-bundle surface. The public MCP surface also exposes `clink` plus workflow orchestration tools (`list_workflows`, `resume_workflow`, `run_workflow`), but it does not expose primitive filesystem read, list, search, or delete tools.
+
+### Context builder secret material (default-on)
+
+The `context_builder` secret filter is **non-blocking and default-on**. Under the default (`allow_secrets:true`), secret material — API keys, SSH/private keys, tokens, and secret-bearing files such as `.env`, `.pem`, `id_rsa`, and `credentials.json` — is included **verbatim, BY DESIGN**:
+
+- in curated bundles (`bundle.md` and the candidate slices),
+- in the curator/finalizer delegate packets, and
+- flowing onward to council member CLIs and their upstream providers.
+
+Secrets are needed to probe, so this is intentional. The task/prompt-string guard (`assertNoHighConfidenceSecretsInTask`) is gated by the same flag, so with `allow_secrets:true` the `task` / `cb_task` string may carry secret material.
+
+**On-disk persistence consequence.** When secrets are allowed, they are written durably to the runs directory (`CLINKX_CONTEXT_BUILDER_RUNS_DIR`) — `bundle.md`, `slices.jsonl`, `search.jsonl`, and `inputs.snapshot.json` (the task string). In workflows the curated bundle is copied into the workflow run directory, which is **retained on disk for async (`succeeded_async`) runs** so its result stays pollable. Treat these artifacts as secret-bearing and apply manual retention/cleanup accordingly.
+
+**Escape hatch — restore fail-closed omission/redaction.** Set any of, in precedence order (highest wins):
+
+1. per-call `allow_secrets:false` (standalone `context_builder` / `refine_context_run`),
+2. workflow `cb_allow_secrets:false`,
+3. env `CLINKX_CONTEXT_ALLOW_SECRETS=false` (environment-wide; honored by both standalone and workflow paths).
+
+The effective default when none is set is `true`.
+
+**Caveat — workflow task-secret guard requires the preflight runner.** In workflows, the persisted-task-text guard runs via the injected context-builder runner. Under the hard preflight bypass (`CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false`) no runner is injected, so the guard is inert and `cb_allow_secrets:false` does **not** gate persisted task text (`inputs.snapshot.json`) in that mode — consistent with that switch being a total context_builder bypass (bundles/delegate off).
+
+**What allowing secrets does NOT change.** Permitting secrets into bundles does **not** leak them into logs or child process environments. The following remain redacted/enforced regardless of `allow_secrets`:
+
+- subprocess environment-variable scrubbing (`src/env.ts`),
+- pino / stderr **log** redaction,
+- Elaris remote-session redaction (`src/elaris/redact.ts`),
+- path-traversal / allowed-root / absolute-path safety.
+
+### Unsafe args
+
+- `unsafe_args` from adapter config are always merged with `args` at runtime.
+- Since clink spawns CLIs non-interactively, permission-bypass flags must be present for the subprocess to function.
+
+### Environment sanitization
+
+- Subprocess environment starts from a minimal baseline (`PATH`, `HOME`, `USER`, `LANG`, `TMPDIR`).
+- Additional env from adapter config is merged via `env_allowlist`.
+- Secrets are redacted in logs.
+
+### Result contract safety
+
+- Only allowlisted filenames (`RESULT.md`, `RESULT.json`) are read from run directories.
+- Files must be regular files (not symlinks) — verified via `lstat`.
+- File `realpath` must resolve within the run directory.
+
+### Subprocess hardening
+
+- `shell: false` — no shell interpretation of arguments.
+- Bounded timeouts with SIGTERM → SIGKILL escalation.
+- Output capture with byte limits: `CLINKX_MAX_CAPTURE_BYTES` controls retained head+tail ring buffer size (falls back to `CLINKX_MAX_OUTPUT_BYTES` if not set).
+- Process-group kill on timeout/cancellation.
+
+### Dashboard session logs
+
+The dashboard session log is a local, private, observability-only record, not an
+execution or authorization channel. Workflow-call, activity, and context-run
+lanes accept normalized events only; arbitrary provider payloads are not a
+journal input. Before any filesystem write, the redactor applies credential
+patterns and absolute user-home path removal independently of `allow_secrets`
+and the tool-arguments persistence gate.
+
+Detector classes include normalized structured keys and credential suffixes;
+credential assignments; Authorization/Proxy-Authorization with any scheme,
+Cookie/Set-Cookie header lines, arrays, arguments, and name/value pairs;
+shape-based credential flags; password-bearing URL
+userinfo; vendor token prefixes and bounded three-segment JWTs; embedded JSON
+with shell-escaped quotes or Unicode-escaped keys; private-key signals;
+sensitive query values; and absolute user-home paths. Regardless of program,
+`-u/--user/--proxy-user/--http-user/-a/--auth` operands are redacted only when
+they contain a `user:secret` colon pair; `-b/--cookie` operands only when they
+contain `name=value`; `--password/--http-password/--proxy-password/--passwd`
+operands always. Attached `-pSECRET` is redacted only after an unquoted
+mysql/mariadb token in the same command segment, unless the operand is
+port-shaped. Sensitive `NAME=value` assignment words are redacted anywhere;
+quoted command strings (such as `bash -lc '…'`) get one bounded nested pass.
+The accepted trade-off is over-redaction of unrelated colon-pair operands such
+as `docker run -u 1000:1000`, while `ssh -p 22`, `docker -p 8080:80`,
+`tar -u archive`, and `wget -b URL` stay intact.
+Tool output text uses the same text detectors. Derived
+summaries use sanitized values before truncation; a recognized embedded
+sensitive fragment that cannot be safely rewritten is withheld.
+
+`CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED` defaults off and is read
+once per producer at creation; only exact `true` enables arguments, derived
+summaries, and `redaction.coverage: "pattern_best_effort"`. Coverage describes
+the method; status/count report detected matches, not cleanliness. Readers
+always accept the extended fields. Deploy capable backend/browser readers
+before enabling producers, and keep them during rollback until extended
+journals age out: disabling the flag does not scrub existing bytes or restore
+old-reader compatibility. Native projection persists nothing and uses the same
+sanitizer independently of this flag.
+
+Pattern redaction is exposure reduction, not a proof that content is safe.
+Prompts, assistant output, tool summaries, errors, and reasoning may still carry
+sensitive project or personal data. Treat the session-log root and every copied
+value as sensitive. The authenticated UI renders literal text and provides
+chronological, sequence-authoritative Timeline and Conversation views; logs
+never grant replay, approval, cancellation, or other control authority.
+
+Every lane is fenced to the exact immutable parent generation and leaf identity.
+Reads are bounded to 500 events per page and 100,000 events per lane. Workflow
+and activity log availability follows parent retention. Context logs currently
+follow the parent context-run/manual lifecycle because there is no independent
+context-run pruner; operators must include them in context-run cleanup policy.
+
+New parents persist a private `.session-log-generation` token so producers and
+the dashboard resolve one journal across bind mounts even when their filesystem
+device/inode identities differ. Dashboard-local generations remain the parent
+authorization boundary; the portable token is read only after that check. A
+missing sidecar is legacy same-filesystem behavior, while a malformed,
+symlinked, or substituted sidecar fails closed without scanning journal
+directories. Retention quarantines and reverifies the exact portable generation
+before recursive deletion. As elsewhere in the local state tree, an actively
+hostile process running as the same OS user is outside this filesystem boundary.
+
+### Dashboard passkey state
+
+Passkey mode stores only the WebAuthn user handle, public credential IDs and
+keys, signature counters, transports, labels, and timestamps. It never stores a
+private key or biometric. The credential document is a strict, versioned JSON
+file under `CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR` (host default:
+`${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/webauthn`; container:
+`/data/dashboard-credentials`); the directory and file must be mode `0700` and
+`0600`, respectively.
+
+Writes use a synced temporary file, atomic rename, and directory sync behind a
+portable owner-token lease with heartbeat/stale-owner recovery and a bounded
+synchronous publication fence. This is a single-host filesystem protocol, not
+distributed locking or absolute CAS against a process paused beyond the lease.
+If a post-rename callback or durability operation fails, one terminal
+`dashboard_credential_store_post_publication_failure` diagnostic is emitted and
+mutations stay disabled until an operator investigates and restarts/reopens the
+store. Current healthchecks intentionally do not observe that latch.
+
+Sessions, challenges, and the one-time first-enrollment code are bounded,
+in-memory state and therefore expire on restart. Challenge capacity is
+partitioned into 96 login and 32 registration entries with no live eviction;
+verification capacity is 8. Saturation fails fast with HTTP 503 `auth_busy` and
+`Retry-After: 1`.
+
+Localhost cookies are not port-scoped by browsers. A successful local WebAuthn
+login therefore creates a separate 32-byte random origin proof bound to the
+in-memory session. The local login response returns that proof to the browser,
+which keeps it in `sessionStorage` under the exact origin (including port) and
+sends it as `X-ClinkX-Local-Origin-Proof` on passkey status, auth, and data
+requests. Local authenticated access requires both the `HttpOnly` session cookie
+and a constant-time-valid proof, so replaying a cookie from another localhost
+port is insufficient even when `Origin` is absent. The proof is never a cookie,
+server-persisted value, or log field. Logout, invalid/expired auth state, and
+authenticated 401 responses clear it. Same-tab reload can restore it; a browsing
+context without it must reauthenticate. Cloud passkey behavior remains
+cookie-only and its login response remains `{"verified":true}`.
+
+The first enrollment code is printed only when no credential exists. After the
+first durable credential is registered, recovery requires an authenticated
+session to add another passkey; losing every enrolled passkey requires backed-up
+re-enrollment into deliberately empty state. Cloud deployment is limited
+to one replica because session and challenge state are process-local and the
+credential writer is single-owner. Credential state belongs on a narrow
+independent read-write volume; operator progress-report status pins belong on
+a second independent read-write volume. All other dashboard input mounts remain
+read-only. Deployment preflight classifies strict-v1 absent/zero/nonzero state
+only; store open remains the sole RP-ID authority.
+
+Bearer mode remains a transitional rollback path until both a real local
+platform-passkey ceremony and a live same-origin Traefik ceremony have passed.
+The authenticated dashboard response path must not log enrollment codes,
+session cookies, WebAuthn payloads, or Authorization headers, and an edge
+`Permissions-Policy` must not disable `publickey-credentials-get` or
+`publickey-credentials-create`.
+
+## What ClinkX Does NOT Secure
+
+### No sandbox
+
+The spawned CLI process (e.g., `agy`, `codex`, `claude`, `grok`) runs with **full user permissions**. It can:
+
+- Read/write any file the user can access
+- Make network requests
+- Execute other programs
+- Modify system state
+
+Allow-roots validation constrains which paths ClinkX *accepts as input* — it does not restrict what the CLI process can do once spawned.
+
+The `agy` (Google Antigravity CLI) adapter runs **without `--sandbox`** — fully unsandboxed, exactly like the `codex`, `claude`, and `grok` adapters. Note that even agy's `--sandbox` flag would only enable **terminal restrictions**, not filesystem-write containment (on macOS it was verified to NOT contain filesystem writes), so it is not a security boundary either way. The shipped `agy` adapter always applies `--dangerously-skip-permissions` (its `unsafe_args` are merged unconditionally), which auto-approves all tool permission requests without prompting. Additionally, each agy headless run accumulates roughly six state files under `~/.gemini/antigravity-cli/`; this is minor disk growth to be aware of for long-lived servers.
+
+The shipped `grok` adapter is the same class of unsandboxed CLI: `--always-approve` is in `args` (not `unsafe_args`), and there is no tool denylist. Local auth is OAuth via `~/.grok/auth.json` (`HOME` is in the sanitized baseline); `XAI_API_KEY` is the extra `env_allowlist` entry. The process inherits the user's `~/.grok` plus Claude-compat MCP the same way Claude inherits `~/.claude`. Recursion into a host-configured clinkx MCP is a host-config issue, not an adapter sandbox.
+
+### No network restrictions
+
+ClinkX does not proxy, filter, or restrict network access by the subprocess.
+
+### No filesystem isolation
+
+The subprocess shares the user's filesystem. The run directory is a convenience for result contracts, not a security boundary.
+
+`context_builder` artifacts are also not a security boundary. They are durable files intended to be attached to later `clink` calls. Treat `manifest.json`, `bundle.md`, and candidate artifacts as local working artifacts with manual retention and cleanup expectations.
+
+### Delegate mode is not a sandbox
+
+When `context_builder` runs with `delegate.enabled:true`, curator and finalizer
+providers are invoked through configured CLI adapters and the existing runner
+boundary. ClinkX does not add filesystem, process, or network isolation for
+those delegate calls.
+
+Delegate provider output is treated as untrusted advice, not source authority:
+
+- The server sends bounded local candidate packets, not arbitrary filesystem
+  access instructions.
+- Providers must return one strict JSON object; truncation, salvage, prose,
+  fenced blocks, or malformed output are rejected.
+- Accepted candidate IDs and ranges must map back to local discovery records.
+- Source content is reconstructed locally from server-generated slices.
+- Budgets and high-confidence secret checks are reapplied after delegate
+  selection.
+- Raw curator/finalizer output is not persisted in receipts, manifests,
+  summaries, bundles, or candidate artifacts.
+
+`failure_policy:"fallback"` publishes deterministic local selection as a
+partial v2 run when delegate curation fails. `failure_policy:"fail"` returns an
+error and does not publish `manifest.json`. Parent cancellation stops active
+delegate work through the existing pipeline/runner cancellation path and does
+not publish a successful run.
+
+### What ClinkX cannot secure (practical limits)
+
+- **CLI behavior**: If the CLI decides to read other files, execute programs, or make network requests, ClinkX does not (and cannot) prevent that in v1.
+- **Prompt injection inside the CLI**: ClinkX can validate inputs to `clink`, but cannot guarantee the downstream model will obey your safety constraints.
+- **External side-effects**: Any side-effects performed by the subprocess (disk writes, network calls) happen with the user’s permissions.
+
+## Recommendations
+
+1. **Run as a least-privilege user** when possible.
+2. **Review adapter configs carefully** — `command`, `args`, and `unsafe_args` determine what gets executed.
+3. **Set `CLINKX_ALLOWED_ROOTS` explicitly** in production to limit input surface.
+4. **Review `unsafe_args` in your adapter configs** — they are always included at runtime.
+5. **Treat the spawned CLI as fully trusted code** — because it runs with your permissions.
+6. **Treat context_builder artifacts as local source-derived files** — review them before passing them to a powerful downstream CLI.
+7. **Configure delegate providers deliberately** — there are no built-in curator or finalizer defaults, and delegate adapters run with the same process and filesystem caveats as `clink`.
+
+## Troubleshooting
+
+### “Path … is outside allowed roots”
+
+- Set `CLINKX_ALLOWED_ROOTS` to include the workspace roots you want to allow.
+- Paths are validated via `realpath` (symlink escapes are blocked).
+
+### “FATAL: cwd resolves to filesystem root”
+
+- Start the server from a non-root working directory, or set `CLINKX_ALLOWED_ROOTS` explicitly.
+
+### “Adapter … requires a TTY”
+
+- ClinkX v1 does not support PTY/TTY emulation. Use an adapter/CLI mode that can run non-interactively, or wait for a future version that adds PTY support.
+
+### “Unknown cli_name …”
+
+- Ensure your adapter JSON is discoverable (see `docs/configuration.md`) and names are unique.
+
+### “Concurrency limit reached …”
+
+- Increase `CLINKX_MAX_CONCURRENT`, or retry later. ClinkX fails fast (it does not queue requests).
+
+### Timeouts / truncated output
+
+- Increase adapter `timeout_seconds` or request `timeout_seconds`.
+- If output is truncated at the capture layer, increase `CLINKX_MAX_CAPTURE_BYTES` (default 2MB, controls head+tail ring buffer retention). Falls back to `CLINKX_MAX_OUTPUT_BYTES` if not set.
+- Set `CLINKX_STRICT_FIDELITY=true` to make capture-layer truncation a hard error for stdout-extracted (non-result-contract) calls.

package/docs/verification/README.md

@@ -0,0 +1,59 @@
+# Verification Procedures
+
+The npm-installed ClinkX MCP server exposes provider readiness and project
+verification tools. An MCP client can use them without shell access, a ClinkX
+checkout, Git, a browser, or ClinkX development dependencies. Node 24 or newer
+and the tools required by your own project checks must be installed on the MCP
+server's host.
+
+| MCP tool | Purpose | Guide |
+| --- | --- | --- |
+| `provider_doctor` | Separate provider configuration, executable, authentication, and startup readiness; authentication probes are explicit | [Provider readiness](../configuration.md#provider-readiness-doctor) |
+| `verification_run` | Execute a reviewed project manifest and retain private evidence for the identified state | [Project checks](project-checks.md), [example manifest](project-checks.example.json) |
+| `run_workflow` with `verified-repair` | Explicit scoped in-place repair with native and independent causal checks; owner acceptance stays separate | [Native repair setup](project-checks.md#native-verified-repair), [invocation](../engineering-recipes.md#built-in-native-verified-repair) |
+| `verification_inspect` | Inspect retained evidence with the owner's original expectations digest; execute no project commands | [Project checks](project-checks.md) |
+
+These guides and the example manifest ship in the npm package. The engineering
+recipe invocation guide also ships; the built-in native workflows require no companion checkout. Manual recipe instructions use
+the separately installed companion skill described in
+[engineering recipes](../engineering-recipes.md).
+
+## ClinkX source-checkout procedures
+
+The following regression procedures exercise ClinkX's own runtime with controlled
+fixtures. Their scripts and fixtures require a source checkout; their guides are
+also included in the package. They do not replace the canonical check
+(`npm run build:all && npm test`).
+
+Each source procedure names one feature and states its prerequisites, exact commands,
+the assertions it proves, the evidence to keep, cleanup, and known limits.
+
+| Procedure | Feature | Surface exercised |
+| --- | --- | --- |
+| [dashboard-real-disk.md](dashboard-real-disk.md) | Dashboard serves persisted run history and refreshes a same-generation state replacement | Real dashboard CLI, HTTP API, Chromium, files on disk |
+| [workflow-handoff.md](workflow-handoff.md) | Workflow producers deliver the correct persisted bytes to a final consumer; absent producer evidence remains missing | Real YAML loader, MCP STDIO child, workflow engine, validators, artifact store, host coverage evaluator |
+
+General rules:
+
+- Build once, then run invocations that do not build.
+- Give every invocation its own attempt directory under a private evidence
+  root outside the checkout (`chmod 700`).
+- A zero exit status is not proof. Check the retained report for the exact
+  required test and its status.
+- Raw reports, traces, and logs can contain credentials. Keep them private;
+  share only checked, token-free summaries.
+
+## Maintaining the feature map
+
+Each row above maps one feature to one procedure. When a procedure stops
+passing, classify the cause before repairing it:
+
+| Class | Meaning | Example | Repair in |
+| --- | --- | --- | --- |
+| Documentation drift | The product changed on purpose; the procedure or its selectors did not follow. | A UI redesign moved labels the spec asserted. | The procedure and spec. Keep the assertion's intent; record any check that can no longer be observed. |
+| Harness defect | The fixture, config, or runner misreports the result. | A fixture that treats an unsolicited exit as a clean shutdown; a runner that kills the fixture before its cleanup. | The fixture or config, with a subprocess test or a repeated procedure run that fails without the repair. |
+| Product regression | The feature itself no longer behaves as intended. | The inspector stops refreshing after a state replacement. | The product code, not the procedure. |
+
+After any repair, repeat the affected procedure and keep the new attempt's
+evidence. Do not weaken an assertion to make drift pass. Add a row here when a
+new procedure is added, and remove a row only when its feature is removed.