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
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@
anything that sends data or reaches an unknown host waits for you.</b></p>

<p align="center">
<img src="site/assets/demo.svg" alt="An agent (here Claude Code, in a lea container) fetches a page of pkg.go.dev, a trusted host: the lockhttp gate lets the GET through at once. It then POSTs a build report to hooks.example.net, an unknown host: the gate holds the request, and an approval screen shows it with the body preview masked (the email as j***(20), the token as &lt;secret&gt;). The human answers n token in body; the agent gets a 403 E_DENIED, and the gate's audit records both decisions." width="900">
<img src="site/assets/demo.svg" alt="An agent (here Claude Code, in a lea container) fetches a page of pkg.go.dev, a trusted host: the lockhttp gate lets the GET through at once. It then POSTs a build report to hooks.example.net, an unknown host: the gate holds the request, and a question shows in lox run, in your own terminal. You press d to read the whole masked screen (the author's email shows as j***(23)), then n to deny; the agent gets a 403 E_DENIED, denied on the hub, and the gate's audit records both decisions." width="900">
</p>
<p align="center"><sub>An agent (here Claude Code, left, in a lea container) and the approval screen (right). Drawn in the console's frame from before the hub: today you answer in <code>lox run</code>.</sub></p>

<p align="center">
<a href="#quick-start">Quick start</a> ·
Expand Down
5 changes: 4 additions & 1 deletion docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,10 @@ no host install. Coming from v0.1.0's
install](docker.md#migrating-from-a-host-install).

The README's demo is generated by [`scripts/brand/demo.py`](../scripts/brand/demo.py):
`python3 scripts/brand/demo.py > site/assets/demo.svg`.
`python3 scripts/brand/demo.py > site/assets/demo.svg`. Its terminals show
the capture in `scripts/brand/demo-capture/`: output of the gate and of
`lox run`, taken in two separate test runs and joined by hand
([how](../scripts/brand/demo-capture/README.md)).

Accounts, volumes, the exact `docker run` of each command, and what Docker
does and does not separate: [docs/docker.md](docker.md). Every command
Expand Down
119 changes: 119 additions & 0 deletions internal/gate/democapture_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
package gate

import (
"crypto/tls"
"encoding/json"
"encoding/pem"
"fmt"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"

"github.com/DavidGodefroid/lockkit/hubclient"
"github.com/DavidGodefroid/lockkit/ticket"
)

// containerConn is a connection that says it arrived on a container's
// network address, as one does in lea's proxy container: sources.json names
// the container by that address.
type containerConn struct {
net.Conn
local net.Addr
}

func (c containerConn) LocalAddr() net.Addr { return c.local }

type containerListener struct{ net.Listener }

func (l containerListener) Accept() (net.Conn, error) {
c, err := l.Listener.Accept()
if err != nil {
return nil, err
}
return containerConn{c, &net.TCPAddr{IP: net.ParseIP("10.89.3.2"), Port: 3130}}, nil
}

const demoCapturePolicy = `
[profiles.default]
hold = "60s"
trusted = ["pkg.go.dev"]
`

// TestDemoCapture is not a test: it writes the gate's half of the README
// demo's capture (scripts/brand/demo-capture/README.md). It is skipped
// unless LOCKHTTP_DEMO_OUT names a directory, and needs curl:
//
// LOCKHTTP_DEMO_OUT=/tmp/capture go test ./internal/gate -run TestDemoCapture -count=1
//
// It runs the demo's two requests with curl through a gate that reads a
// sources.json as lea writes it, against the tests' fake hub and a stand-in
// upstream, and writes gate.txt (curl's output, then the gate's audit
// records) and ticket.json (the ticket the gate signed for the held POST).
// The fake hub denies the ticket as lox run's n does: no reason, facade tty.
func TestDemoCapture(t *testing.T) {
out := os.Getenv("LOCKHTTP_DEMO_OUT")
if out == "" {
t.Skip("LOCKHTTP_DEMO_OUT is not set")
}
write := func(path string, b []byte) {
t.Helper()
if err := os.WriteFile(path, b, 0o644); err != nil {
t.Fatal(err)
}
}
dir := t.TempDir()
sources := filepath.Join(dir, "sources.json")
b, _ := json.Marshal(map[string]any{"version": 1,
"networks": []map[string]string{{"local_ip": "10.89.3.2", "container": "lea-ab12cd34ef", "project": "shop"}},
"agents": []map[string]string{{"token_sha256": sum([]byte("t3")), "container": "lea-ab12cd34ef", "agent": "dev-3",
"role": "dev", "parent": "lead-1", "task_id": "t-42", "branch": "feat/ci-report"}}})
write(sources, b)
e := newEnvHub(t, demoCapturePolicy, true, func(c *hubclient.Config) { c.Instance = "web" }, nil, func(c *Config) {
c.Sources = NewSources(sources)
// The stand-in upstream's certificate is httptest's, not pkg.go.dev's.
c.UpstreamTLS = &tls.Config{InsecureSkipVerify: true}
})
// The senders are confined (sources.json names them): the policy need
// not allow unconfined ones. Wait for the gate to read it again.
e.console.pol.Unconfined = false
time.Sleep(300 * time.Millisecond)
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { ln.Close() })
go func() { _ = e.gate.Serve(t.Context(), containerListener{ln}) }()
e.backend("pkg.go.dev", true, http.HandlerFunc(ok))
e.remap("pkg.go.dev", "443")

caFile := filepath.Join(dir, "ca.pem")
write(caFile, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: e.gate.cfg.Certs.(localCerts).c.Cert.Raw}))
write(filepath.Join(dir, "report.json"), []byte(`{"build":"ok","author":"jean.dupont@example.org"}`))
var sb strings.Builder
curl := func(args ...string) {
cmd := exec.Command("curl", args...)
cmd.Dir = dir
proxy := "http://dev-3:t3@" + ln.Addr().String()
cmd.Env = append(os.Environ(), "HTTPS_PROXY="+proxy, "HTTP_PROXY="+proxy, "CURL_CA_BUNDLE="+caFile, "NO_PROXY=", "no_proxy=")
o, err := cmd.CombinedOutput()
fmt.Fprintf(&sb, "$ curl %s\n%s[exit: %v]\n", strings.Join(args, " "), o, err)
}
curl("-sS", "-o", "/dev/null", "-w", "%{http_code}\n", "https://pkg.go.dev/net/http")
go func() {
tk := e.hub.waitTickets(1)[0]
j, _ := json.MarshalIndent(tk, "", " ")
write(filepath.Join(out, "ticket.json"), j)
time.Sleep(300 * time.Millisecond)
e.hub.decideWith(tk, ticket.Denied, "", nil, "", func(d *ticket.Decision) {
d.Approver = ticket.Approver{ID: "host:uid:1000", Display: "alice"}
})
}()
curl("-sS", "-X", "POST", "https://hooks.example.net/build", "-H", "content-type: application/json", "-d", "@report.json")
fmt.Fprintf(&sb, "== AUDIT\n%s\n", e.auditText())
write(filepath.Join(out, "gate.txt"), []byte(sb.String()))
}
79 changes: 79 additions & 0 deletions scripts/brand/demo-capture/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# The demo's capture

`scripts/brand/demo.py` draws `site/assets/demo.svg` (the README's and the
site's demo) from the files here. They are output of the code, but **not of
one run of a lea + `lox run` stack**: two runs, in two repositories, joined
by hand.

Sources: lockhttp `2f0d37f`, lockhub `4d94ef1`, both on lockkit `v0.20.0`.

## The files

| File | What it is | Produced by |
|---|---|---|
| `gate.txt` | The two `curl` commands, their output as curl printed it, then the gate's audit records. | Run 1 |
| `lox-run-idle.ans`, `lox-run-question.ans`, `lox-run-details.ans`, `lox-run-denied.ans` | The frames `lox run` drew, 80×26, with their colours (SGR): before the ticket, the question, the question after `d`, after `n`. | Run 2 |
| `loxrun_demo_test.go.txt` | The test of run 2. It belongs in lockhub, so it is kept here as text and is not built. | — |

## Run 1: the gate (this repository)

`internal/gate/democapture_test.go`, `TestDemoCapture`, skipped unless
`LOCKHTTP_DEMO_OUT` names a directory. Needs `curl`.

```sh
LOCKHTTP_DEMO_OUT=/tmp/capture go test ./internal/gate -run TestDemoCapture -count=1
```

It starts the gate of `internal/gate` as the package's tests do, with TLS
decryption, a `sources.json` as lea writes it (container `lea-ab12cd34ef`,
agent `dev-3`) and the policy `trusted = ["pkg.go.dev"]`, `hold = "60s"`.
Real `curl`, with `HTTPS_PROXY` set as lea sets it, sends the GET and the
POST. It writes `gate.txt` and `ticket.json`, the ticket the gate signed for
the held POST.

What is not the real thing in this run:

- **The hub is the test suite's fake hub.** It denies the ticket the way
`lox run`'s `n` does, as run 2 showed: no reason, facade `tty` (the gate
turns an empty reason into `denied on the hub`).
- **The upstream is a stand-in**, not pkg.go.dev: the `200` is the gate's
answer for it.
- The connections are given the container's network address by the test
(in lea, the proxy container has that address).

## Run 2: `lox run` (lockhub)

In a throwaway worktree of lockhub at `4d94ef1`:

1. In `internal/loxrun/e2e_test.go`: `inst = "shop"` becomes `"web"`, the
size `100, 30` becomes `80, 26`, `Workspace: "~/e2e"` becomes
`"~/Documents/shop"`.
2. Copy `loxrun_demo_test.go.txt` to `internal/loxrun/zz_demo_test.go`.
3. `LOCKHTTP_DEMO_OUT=/tmp/capture go test ./internal/loxrun -run TestLockhttpDemo -count=1`

It uses lockhub's e2e world: the real hub, a real lockkit hub client, and
`lox run` driven by key presses. It writes the four frames and
`decision.txt`, the hub's signed decision.

## The join

Run 2 does not receive run 1's ticket over the wire. It reads `ticket.json`
and **builds and signs a ticket again**, with the same risk, flags,
requester, header, body lines and warning, the way `internal/gate/hub.go`
does (`ticket.NewTicket`, `render.MaskScreen` with the same detectors),
under the lock key of lockhub's harness. So:

- the request id is the same on both sides, the ticket id is not;
- the clocks are those of two runs, a few seconds apart;
- the denial in `gate.txt` was given by run 1's fake hub, not by the `n`
pressed in run 2.

## Typed in `demo.py`, not captured

The prompt, the two `curl` commands as shown, Claude Code's frame around a
command and its output (`● Bash(…)`, `└`, `Running…`), the pane titles, the
`FREE` / `ASK` / `403` badges, the two "you press…" hints (`lox run` does
not echo keys), the audit box's title and the three captions. The audit
lines are records of `gate.txt` with fields left out where they show `…`;
`gate.txt` holds a third record (`refused`, the answer sent to the agent)
that the demo does not show.
14 changes: 14 additions & 0 deletions scripts/brand/demo-capture/gate.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
$ curl -sS -o /dev/null -w %{http_code}
https://pkg.go.dev/net/http
200
[exit: <nil>]
$ curl -sS -X POST https://hooks.example.net/build -H content-type: application/json -d @report.json
LockHTTP refused this request (E_DENIED): denied on the hub
Do not retry the same request; ask the user.
request id: h-mwm16i9i-c991bc1966bb624f
[exit: <nil>]
== AUDIT
{"ts":"2026-11-18T11:21:23.949Z","event":"free","profile":"default","decision":"free","request_id":"h-mwm16i95-8f20dc2b6683da80","container":"lea-ab12cd34ef","project":"shop","via":"direct","agent":"dev-3","attribution":"proxy-auth","role":"dev","parent":"lead-1","task_id":"t-42","branch":"feat/ci-report","phase":"http","tls":"mitm","method":"GET","host":"pkg.go.dev","port":443,"path":"/net/http","req_headers":["accept","user-agent"],"rule":"trusted","class":"read","status":200,"resp_bytes":184,"duration_ms":4,"policy_fp":"sha256:ffe9c710b3ecc681e9f1f83e4a6b2a5ded6b1c439326de2c7c038bbd8de8f52c"}
{"ts":"2026-11-18T11:21:24.339Z","event":"denied","profile":"default","decision":"denied","warnings":["unknown host hooks.example.net"],"reason":"denied on the hub","approval":"hub","ticket":"01M7Q67PRCDJT3ACXBTEMMVS5Z","approver":{"id":"host:uid:1000","display":"alice"},"facade":"tty","hub_sig":"mBpqSdMPx0OymG7pcZYs01YEun274zV3xSRnwTMi9xKbpOwLVezSpvmWJpVDtubxIcOLyS3UdSn-VvhZBu2qDQ","request_id":"h-mwm16i9i-c991bc1966bb624f","container":"lea-ab12cd34ef","project":"shop","via":"direct","agent":"dev-3","attribution":"proxy-auth","role":"dev","parent":"lead-1","task_id":"t-42","branch":"feat/ci-report","phase":"http","tls":"mitm","method":"POST","host":"hooks.example.net","port":443,"path":"/build","req_headers":["accept","content-length","content-type","user-agent"],"req_bytes":49,"body_fp":"json:a20a0c27eefde4875a3a193fa2802e3e8de1e09d24334ce7633b23fc8c09b2fd","rule":"default:write","class":"write","policy_fp":"sha256:ffe9c710b3ecc681e9f1f83e4a6b2a5ded6b1c439326de2c7c038bbd8de8f52c"}
{"ts":"2026-11-18T11:21:24.339Z","event":"refused","profile":"default","decision":"refused","code":"E_DENIED","warnings":["unknown host hooks.example.net"],"reason":"denied on the hub","request_id":"h-mwm16i9i-c991bc1966bb624f","container":"lea-ab12cd34ef","project":"shop","via":"direct","agent":"dev-3","attribution":"proxy-auth","role":"dev","parent":"lead-1","task_id":"t-42","branch":"feat/ci-report","phase":"http","tls":"mitm","method":"POST","host":"hooks.example.net","port":443,"path":"/build","req_headers":["accept","content-length","content-type","user-agent"],"req_bytes":49,"body_fp":"json:a20a0c27eefde4875a3a193fa2802e3e8de1e09d24334ce7633b23fc8c09b2fd","rule":"default:write","class":"write","policy_fp":"sha256:ffe9c710b3ecc681e9f1f83e4a6b2a5ded6b1c439326de2c7c038bbd8de8f52c"}

26 changes: 26 additions & 0 deletions scripts/brand/demo-capture/lox-run-denied.ans
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
 lox run  AUTO  ~/Documents/shop ● hub up · 1 lock
 connected none yet: a lock connects on its agent's first request
────────────────────────────────────────────────────────────────────────────────




















12:21:49 dev-3 ⇄ web - write from container lea… ✘ denied
────────────────────────────────────────────────────────────────────────────────
Shift+Tab mode a audit ? help q quit
26 changes: 26 additions & 0 deletions scripts/brand/demo-capture/lox-run-details.ans
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
 lox run  AUTO  ~/Documents/shop ● hub up · 1 lock · 1 waiting
 connected none yet: a lock connects on its agent's first request
────────────────────────────────────────────────────────────────────────────────
 ┌ ◆ QUESTION write on web ───────────────────────────────────────────────────┐
 │ dev-3 asks (unverified name) · ⇄ lockhttp · expires in 23h59m │
 │ POST hooks.example.net · lea-ab12cd34ef │
 │  from container lea-ab12cd34ef (project shop) · agent dev-3 (declared, pr…│
 │  POST mitm://hooks.example.net/build │
 │  body 49 bytes application/json json:a20a0c27eefde4… │
 │  headers: accept content-length content-type user-agent │
 │  task t-42 · role dev · parent lead-1 · branch feat/ci-report │
 │  decided by: default:write │
 │  │
 │  preview (masked): │
 │  {"build":"ok","author":"‹j***(23)›"} │
 │  │
 │  client gone: y lets the same request through once in the next 10 minutes │
 │  request h-mwm16i9i-c991bc1966bb624f │
 │ ! unknown host hooks.example.net │
 │ why asked: this lock's ticket does not name its kind (version 1): asked │
 │ y approve n deny d less x forget profile │
 └────────────────────────────────────────────────────────────────────────────┘

12:21:49 dev-3 ⇄ web - write from container lea… ◆ ask:v1
────────────────────────────────────────────────────────────────────────────────
Shift+Tab mode y/n answer d details a audit ? help q quit
26 changes: 26 additions & 0 deletions scripts/brand/demo-capture/lox-run-idle.ans
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
 lox run  AUTO  ~/Documents/shop ● hub up · 1 lock
 connected none yet: a lock connects on its agent's first request
────────────────────────────────────────────────────────────────────────────────




















 no ticket yet: every ticket and decision of the hub shows here, masked by its…
────────────────────────────────────────────────────────────────────────────────
Shift+Tab mode a audit ? help q quit
Loading
Loading