lockkit

The shared Go core of every Lock: write the operations,
get the console, the approvals, the masking and the audit for free.

Quick start · How it works · Docs · Lock Family

lockkit is the shared foundation of the Lock Family, harness security for AI agents. It holds everything that keeps a secret-holding console separate from an AI agent, asks the human, and records what happened.

A product supplies its names and its operations, through a Backend; lockkit supplies the rest.

[!NOTE] No stability promise before v1. Products pin an exact version. GUIDE.md is the contract between lockkit and the products built on it.

Why lockkit

• One security model for every Lock. The console, its isolated account and socket, and the policy review behave the same in locksql, lockmq, lockfile, lockhttp, locklog and lockssh.
• 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.
• One contract with the hub. Signed tickets and decisions, the client for lockhub, and the launcher verbs lox add calls.

Install

lockkit is a Go library (Go 1.26 or later). Pin an exact version:

go get github.com/DavidGodefroid/lockkit@v0.14.0

To work on a Lock and lockkit together, use an uncommitted go.work (see GUIDE.md § 15).

Quick start

A new Lock builds on lockkit in a few steps, each detailed in GUIDE.md:

1. Declare your product once, a kit.Product with its names (binary, console account, clients group, keychain service, env prefix), and pass it everywhere.
2. Register your refusal codes with refusal.Register: they are part of your client protocol.
3. Implement console.Backend: your IPC methods, Connect, Checks, LoadPolicy and Status.
4. Start the console with one call, console.Run(ctx, P, backend, opts), launched by lockhub (lox run) with the hub options.
5. Expose MCP tools with mcpkit (each a thin adapter over client.Call) and wire the agents with agentwire.
6. Implement the launcher verbs (init, profile add, doctor) with verbs, so lox add can set your Lock up.

var P = kit.Product{
	Name:            "lockmq",                                     // binary, .lockmq/, <config>/lockmq, sockets
	Tagline:         "Your AI reads the queue. You hold the key.", // banner
	Account:         "lockmq",                                     // console account
	ClientsGroup:    "lockmq-clients",                             // may reach the console
	KeychainService: "lockmq",                                     // OS keychain service
	EnvPrefix:       "LOCKMQ_",                                    // LOCKMQ_RUNTIME_DIR, ...
}

Highlights

How it works

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.
• 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.

The product plugs its own operations in between, through console.Backend.

Packages

The full map, with what not to reimplement in your product, is in GUIDE.md § 1 and § 11.

Who uses it

Every Lock is built on lockkit: locksql, lockmq, lockfile, lockhttp, locklog and lockssh. lockhub uses its ticket package to verify what the locks sign, and lea builds on it too.

Safety model

• The agent side holds no secret: credentials, the connection and the approved policy stay in the console's separated account.
• The boundary is the operating system's: separate accounts, the kernel's 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.
• Masking is best effort. PII detection quality: precision and recall per detector and language on a synthetic bench, held to a CI baseline, in pii/testdata/bench/RESULTS.md; its Known gaps section lists what the detectors miss most.

Details: GUIDE.md § 6, § 10 and § 13.

Documentation

The Lock Family

Every Lock is built on the same console, separation and approval model, and one hub approves for all of them. Start at lockfamily.dev.

Contributing · Security · License

• Contributing: lockkit has one owner. Do not copy a package into your product or work around it: ask for the change, as GUIDE.md § 15 describes. Tests: go vet ./... && go test ./....
• Security: report vulnerabilities privately through GitHub security advisories.
• License: Apache License 2.0. See LICENSE and NOTICE.