Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 45 additions & 31 deletions GUIDE.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -1261,13 +1262,17 @@ already holds a `<name>` 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
Expand All @@ -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.
Expand Down Expand Up @@ -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).
Expand All @@ -1355,7 +1362,9 @@ init --trusted`, ...) are removed, not aliased (pre-release).
current directory (§12: `Wiring.Init(agentwire.ProjectRoot(P, cwd),
agent)`), for `<agent>` one of `agentwire.Agents()`. It never asks, is
idempotent, and exits 0 when the files are written or already there.
`lox add` calls `<lock> init claude` from the project root.
`lox add` calls `<lock> init claude` from the project root; for another
agent, run `<lock> init codex`, `<lock> init cursor` or `<lock> init gemini`
yourself.

**`<lock> profile add`** adds one profile to the project's
`.<lock>/config.toml`:
Expand Down Expand Up @@ -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":
Expand All @@ -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 `<lock> doctor --fix --yes --json`.
add` calls `<lock> doctor --fix --yes --json` for locksql, lockmq,
lockhttp and lockssh, and `<lock> 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
Expand All @@ -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:

```
<lock> profile add --non-interactive --json --profile NAME [--production] [--credentials ask|vault --vault-path P] <target flags>
<lock> profile add --non-interactive --json --project ROOT --profile NAME [--credentials ask|vault [--vault-path P]] [--production] <target flags>
<lock> init claude
<lock> doctor --fix --yes --json
<lock> doctor --fix --yes --json # or doctor --json, see above
```

then `lox add <lock> <instance>` with that profile, and `lox run`. The
Expand Down
44 changes: 27 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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`
Expand Down Expand Up @@ -105,8 +106,9 @@ var P = kit.Product{
<td width="50%" valign="top">

**🎭 Masking built in**<br>
`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.

</td>
</tr>
Expand All @@ -123,8 +125,8 @@ signed decisions.

**🔌 Any MCP client**<br>
`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.

</td>
</tr>
Expand All @@ -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.
Expand All @@ -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).
Expand All @@ -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).
Expand Down Expand Up @@ -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 `<lock> mcp` (what `<lock> 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),
Expand Down
Loading