diff --git a/GUIDE.md b/GUIDE.md index 72f668f..c49e31f 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,18 +1,18 @@ # lockkit guide -lockkit is the product-neutral half of locksql: everything that keeps a -secret-holding console separate from an AI agent, asks the human, and -records what happened. A product (locksql, lockmq, lockfile, lockhttp, lockssh) supplies its -names and its operations; lockkit supplies the rest. This guide is the -contract between lockkit and the products built on it. - -> Status: v0.3, no stability promise before v1: pin an exact version. -> locksql runs on every package below except `console.Run`/`console.Server`: -> its console still keeps its own modes, status row, policy review and -> start-up sequence (they are interleaved with its SQL state), on lockkit's -> terminal, approvers, isolation checks and request loop. Moving locksql -> onto `console.Run` is the next locksql PR; until then the two copies of -> that logic must stay in step (the framework is the reference). +lockkit is the shared, product-neutral core of every Lock: everything +that keeps a secret-holding console separate from an AI agent, asks the +human, and records what happened. A product (locksql, lockmq, lockfile, +lockhttp, locklog, lockssh) supplies its names and its operations; lockkit +supplies the rest. This guide is the contract between lockkit and the +products built on it. + +> No stability promise before v1: pin an exact version (every product pins +> v0.20.0 today). locksql hosts its backend on `console.Server` +> (`console.NewServer`) but keeps its own start-up sequence instead of +> `console.Run` (its modes, status row and policy review are interleaved +> with its SQL state); the two copies of that logic must stay in step (the +> framework is the reference). ## 1. Package map @@ -40,7 +40,8 @@ contract between lockkit and the products built on it. | `hubclient` | a lock's client for lockhub: signed requests, `Submit` of masked tickets, long-poll of decisions, `Begin`/`Finish` of a decided plan, `Ask` of a connect ticket; the instance key and `hub-key`; `hubclient/hubtest` is a fake hub for tests | | `lazyconn` | backend connections opened on a connect ticket's approval, shared per profile, closed when idle and asked for again; the secret handed from the decider to the lock sealed | | `plans` | a lock's persisted plans awaiting a decision: bound (peer UID, agent token, policy fingerprint, plan hash), single use, 0600 | -| `agentwire` | wiring Claude Code, Codex, Cursor and Gemini CLI to your MCP server, in a project or for the account: merge, never clobber | +| `agentwire` | wiring Claude Code, Codex, Cursor and Gemini CLI to your MCP server, in a project or for the account (Codex's `[mcp_servers]` table: for the account only): merge, never clobber | +| `confine` | the client's self-check of its containment (in a container, no host runtime socket, no Lock Family state, a read-only `.lockfamily/`), sent in `hello` for the console to decide (§10, Confined agents) | | `verbs` | the launcher verbs every lock shares (`init`, `profile add`, `doctor`): the non-interactive form's secret refusal and credential source, the JSON `lox add` reads | ## 2. `kit.Product` @@ -1261,13 +1262,17 @@ already holds a `` server that is not the product's exact entry (action `kept`: a cloned repository may ship one that runs anything), it is foreign: `Init` leaves it, writes nothing to `.claude/settings.local.json`, and the notes only warn the human to check what it runs before approving -it, and to remove it and run init again to wire the product. Codex and Gemini get -600 s tool timeouts from agentwire, which cover the console's 5 minute -approval and a queued call. +it, and to remove it and run init again to wire the product. Codex gets +its MCP server only for the account: a project `Init(root, "codex")` +writes the AGENTS.md section and prints the `[mcp_servers]` table in its +notes, and `InitUser` writes it to `~/.codex/config.toml` (`CODEX_HOME` +when set). Gemini (in a project or for the account) and Codex (for the +account) get 600 s tool timeouts from agentwire, which cover the console's +5 minute approval and a queued call. ## 13. Hub tickets (`ticket`) -In hub mode a lock does not ask the human itself: it pushes a signed +A lock does not ask the human itself: it pushes a signed `ticket.Ticket` to lockhub and acts only on a `ticket.Decision` signed by the hub key it pinned. The package is the contract with lockhub; its `testdata` fixtures are verified by lockhub's CI and do not change within a @@ -1286,9 +1291,9 @@ err = d.Usable(t, time.Now(), ticket.ClampTTL(t.Risk, cfgTTL)) // ErrDenied unle // then consume d.Nonce once, recompute the plan hash, execute ``` -- **Risk classes** are closed: `read`, `read-pii`, `write`, `prod-write`, - `policy-loosen`, `unlock`. Map each operation onto one; an unknown name - does not decode. `Risk.TTL()`: `read` and `read-pii` 1 h (a read left +- **Risk classes** are closed (`ticket.Risks`): `read`, `read-pii`, + `grant`, `write`, `prod-write`, `policy-loosen`, `unlock`. Map each + operation onto one; an unknown name does not decode. `Risk.TTL()`: `read` and `read-pii` 1 h (a read left pending ends by itself), `write` and `policy-loosen` 24 h, `grant`, `prod-write` and `unlock` 4 h; `ClampTTL` lets an instance shorten it, never lengthen it. @@ -1339,14 +1344,16 @@ Another peer UID gets `ErrWrongPeer`, another agent token each other's token, so it is no security boundary). The token itself is never written, only its hash. A plan executing when the lock stopped comes back `Failed` and never runs again. `End` records a denial, -withdrawal or staleness, `WithdrawAll` withdraws every pending plan (a -lock started without its hub), `Prune` expires and removes final plans -after `Retention`; consumed nonces are kept. +withdrawal or staleness, `WithdrawAll` withdraws every pending plan +(legacy: a lock can no longer start without its hub, and no product calls +it), `Prune` expires and removes final plans after `Retention`; consumed +nonces are kept. ## 14. Launcher verbs (`verbs`) `lox add` sets up every lock of a project through the same three verbs -of each lock's launcher (locksql, lockmq, lockfile, lockhttp). The verbs +of each lock's launcher (locksql, lockmq, lockfile, lockhttp, locklog, +lockssh). The verbs are the product's; this section is their contract, and `verbs` holds the checks and JSON shapes they share. Old verbs (`lockmq setup`, `lockhttp init --trusted`, ...) are removed, not aliased (pre-release). @@ -1355,7 +1362,9 @@ init --trusted`, ...) are removed, not aliased (pre-release). current directory (§12: `Wiring.Init(agentwire.ProjectRoot(P, cwd), agent)`), for `` one of `agentwire.Agents()`. It never asks, is idempotent, and exits 0 when the files are written or already there. -`lox add` calls ` init claude` from the project root. +`lox add` calls ` init claude` from the project root; for another +agent, run ` init codex`, ` init cursor` or ` init gemini` +yourself. **` profile add`** adds one profile to the project's `./config.toml`: @@ -1431,9 +1440,11 @@ it detected in the project): | Lock | Target flags `lox add` passes | |---|---| | locksql | `--engine postgres\|mysql\|mariadb\|sqlite`, `--host`, `--port`, `--user`, `--database`, `--tls MODE`; `--path FILE` for sqlite | -| lockmq | `--url` (management API, `http(s)://host:port`), `--user`, `--vhost` (repeatable) | -| lockfile | `--source local\|s3\|sftp` and the flags of that source | +| lockmq | `--url` (management API, `http(s)://host:port`), `--user`, `--vhost` (repeatable), `--amqp-url` | +| lockfile | `--source local\|s3\|sftp` and the flags of that source: `--bucket`, `--endpoint`, `--region`, `--path`, `--host`, `--port`, `--user`, `--auth`, `--key`, `--known-hosts`, `--base-dir` | | lockhttp | none (manual mode only, with lea): `profile add --non-interactive --profile NAME` adds a profile with the lock's default policy | +| locklog | `--only` (the log directories) | +| lockssh | `--host`, `--port`, `--user`, `--auth`, `--key`, `--known-hosts`, `--allow` (repeatable), `--exec` | A profile already in the config is never rewritten: `profile add` fails with code `exists` and writes nothing. `lox add` takes `exists` as "kept": @@ -1458,7 +1469,10 @@ The exit status is 0 exactly when no check fails (a warning does not fail). A doctor that could not check (a usage error, `--fix` refused) prints a `verbs.Error` instead: `lox add` tells the two apart by the `checks` key (`verbs.Doctor`) or the `code` key (`verbs.Error`). `lox -add` calls ` doctor --fix --yes --json`. +add` calls ` doctor --fix --yes --json` for locksql, lockmq, +lockhttp and lockssh, and ` doctor --json` (advisory, no repair) for +lockfile and locklog, whose `--fix` wires the agents for the account, and +for a locksql or lockmq launcher older than v0.13.1 / v0.6.1. **JSON and exit status.** A verb run with `--json` prints one line of JSON on stdout, even when it fails. Its exit status is 0 on success and @@ -1472,9 +1486,9 @@ A non-zero exit with no JSON line on stdout (an older lock, a crash) is What `lox add` calls, for each lock it sets up, from the project root: ``` - profile add --non-interactive --json --profile NAME [--production] [--credentials ask|vault --vault-path P] + profile add --non-interactive --json --project ROOT --profile NAME [--credentials ask|vault [--vault-path P]] [--production] init claude - doctor --fix --yes --json + doctor --fix --yes --json # or doctor --json, see above ``` then `lox add ` with that profile, and `lox run`. The diff --git a/README.md b/README.md index e5a2d3d..3697f63 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,8 @@ lockkit supplies the rest. - **The AI tightens, only the human loosens.** Policy files, their review and the approved store are shared code, not re-implemented per product. - **Masking and audit you do not write twice.** Personal-data detectors, - masks, capped output, error scrubbing and the append-only audit log. + masks, capped output, error scrubbing and the append-only, hash-chained + audit log. - **One contract with the hub.** Signed tickets and decisions, the client for lockhub, and the launcher verbs `lox add` calls. @@ -55,7 +56,7 @@ lockkit supplies the rest. lockkit is a Go library (Go 1.26 or later). Pin an exact version: ```sh -go get github.com/DavidGodefroid/lockkit@v0.14.0 +go get github.com/DavidGodefroid/lockkit@v0.20.0 ``` To work on a Lock and lockkit together, use an uncommitted `go.work` @@ -105,8 +106,9 @@ var P = kit.Product{ **🎭 Masking built in**
-`pii` detects emails, phones, IBANs, cards, national IDs, public IPs and -secrets; `render` caps and escapes output; `sanitize` scrubs errors. +`pii` detects emails, phones, IBANs, cards and national IDs, and on +request IPs, secrets, names, addresses and more; `render` caps and escapes +output; `sanitize` scrubs errors. @@ -123,8 +125,8 @@ signed decisions. **🔌 Any MCP client**
`mcpkit` gives the MCP plumbing; `agentwire` wires Claude Code, Codex, -Cursor and Gemini CLI to your server, in a project or for the account, -merging and never clobbering. +Cursor and Gemini CLI to your server, in a project or for the account +(Codex's MCP server: for the account only), merging and never clobbering. @@ -135,9 +137,9 @@ merging and never clobbering. lockkit splits a Lock in two sides that never share an account: - **The human side, `console`:** it holds the credentials and the only - connection, shows the policy for approval, and serves a socket. In hub - mode it sends masked, signed tickets to lockhub and acts only on a - decision signed by the hub key it pinned. + connection, shows the policy for approval, and serves a socket. It + sends masked, signed tickets to lockhub and acts only on a decision + signed by the hub key it pinned (there is no standalone mode). - **The agent side, `client` + `mcpkit`:** secret-free. It dials the console's socket (peer credentials checked by the kernel) and calls it over newline-delimited JSON-RPC 2.0. @@ -161,17 +163,18 @@ The product plugs its own operations in between, through `console.Backend`. | Data protection | `pii` | value detectors, mask modes, name heuristics, the redacted-reference store | | | `render` | capped, escaped output for agents: `Value` and `Table` | | | `sanitize` | error text scrubbing and terminal-safe text | -| | `audit` | the console's append-only JSONL audit log | +| | `audit` | the console's append-only, hash-chained JSONL audit log | | Transport | `ipc` | console socket, peer credentials, 1 MiB JSON-RPC 2.0 framing, lockkit's methods and error codes | | | `client` | the secret-free side: dial, hello, `Call` | | | `tunnel` | SSH bastion: known_hosts, key/agent/password auth, `Dial` and `NewSession` through it | | | `lazyconn` | backend connections opened on a connect ticket's approval, closed when idle | +| | `confine` | the client's self-check of its containment, sent in `hello` | | Hub | `ticket` | signed tickets and decisions, risk classes and TTLs, ticket kinds, canonical JSON, sealed boxes | | | `hubclient` | a lock's client for lockhub: `Submit`, long-poll of decisions, `Begin`/`Finish`, `Ask`; `hubclient/hubtest` fake hub | | Agent side | `mcpkit` | MCP server and stdio, profile resolution, progress while the human decides, untrusted framing, structured refusals | | | `agentwire` | wiring Claude Code, Codex, Cursor and Gemini CLI to your MCP server | | | `verbs` | the launcher verbs every lock shares (`init`, `profile add`, `doctor`) and the JSON `lox add` reads | -| Release | `update` | cosign keyless signature check of a release artifact, checksums | +| Release | `update` | cosign signature check (keyless or key pair) of a release artifact, checksums | The full map, with what not to reimplement in your product, is in [GUIDE.md § 1](GUIDE.md#1-package-map) and [§ 11](GUIDE.md#11-do-not-reimplement-in-your-product). @@ -196,8 +199,8 @@ builds on it too. peer credentials on the socket. - A policy change the agent proposes can only tighten; loosening is asked of the human, and on production takes the typed profile name. -- In hub mode, a lock executes only on a decision signed by the hub key it - pinned, bound to the exact plan that was approved. +- A lock executes only on a decision signed by the hub key it pinned, + bound to the exact plan that was approved. - The agent must run confined (lea is the reference containment): unconfined agents are refused by default, see [Confined agents](#confined-agents). @@ -248,12 +251,19 @@ reports, and a client too old to report is unconfined (`old_client`). cuts an unconfined connection already open. What this proves, and what it does not: the check makes the safe setup the -default and stops honest or confused agents run on the host. It does not +default and stops honest or confused agents that run a lock client on the +host itself. It does not stop a host process that deliberately lies about where it runs: such a process already runs as you and can drive Docker, so no lock-side check -could stop it. What makes the guarantees hold against prompt injection is -the containment itself: a confined agent (lea) cannot reach the runtime, -the keys or the console's terminal. +could stop it. Nor does it see the agent behind a Lock's launcher: a host +agent that starts ` mcp` (what ` init` wires) runs the client +in a throwaway container with no runtime socket, which reports confined, so +that agent is served while it still runs as you +([#207](https://github.com/DavidGodefroid/lockkit/issues/207)). What makes +the guarantees hold against prompt injection is the containment itself: a +confined agent (lea) cannot reach the runtime, the keys or the console's +terminal. With an agent on the host, the Locks protect against mistakes, +not against a compromised agent. Details: [GUIDE.md § 6](GUIDE.md#6-config-and-policy-the-ai-tightens-the-human-loosens), [§ 7](GUIDE.md#7-ipc-client-tunnel),