gloves 0.5.9

seamless secret manager and handoff
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# Architecture

This document describes the current `gloves` architecture in the repository.

## Components

- `gloves` CLI
  - manages the encrypted store
  - creates and rotates age identities
  - reads, writes, shows, and re-encrypts namespaced secrets
- `gloves-mcp`
  - authenticates MCP sessions with a session token
  - enforces approval tiers
  - exposes redacted MCP tools such as `gloves_get`, `gloves_set`, and `gloves_rotate`
- `@gloves/mcp-client`
  - Bun/TypeScript client that speaks to `gloves-mcp`
  - launches host-local `gloves-mcp` sessions over stdio by default and consumes the secret side-channel
- `@gloves/openclaw`
  - packaged OpenClaw plugin that registers `gloves_*` tools and carries plugin manifest metadata
  - performs secret delivery into environment variables or tmpfs instead of returning plaintext in tool output

For operators, `@gloves/openclaw` is the public install target. The only remaining internal JS
package is `@gloves/mcp-client`, which keeps the broker transport separate from the plugin surface.

## Adapter Boundary

`gloves-mcp` is the canonical machine-facing interface for runtime integrations.
OpenClaw support lives directly in `@gloves/openclaw` over that interface rather than a core
product boundary. OpenClaw operators should install `@gloves/openclaw` on the Gateway host, then
configure the plugin to launch `gloves-mcp` over stdio. The optional unix socket path exists only
as a compatibility transport for legacy deployments.

## Store Layout

The current OpenClaw-oriented store layout is:

```text
<root>/
├── identities/
│   └── <agent>.age
├── store/
│   ├── .gloves.yaml
│   ├── .gloves-meta/
│   ├── agents/
│   └── shared/
└── audit/
```

- `identities/` holds agent age private keys.
- `store/` holds encrypted `.age` files plus namespace `.age-recipients` files.
- `.gloves-meta/` stores redacted metadata used by `show`, `list`, and access bookkeeping.
- `audit/` stores JSONL audit trails.

## Secret Read Flow

Current OpenClaw plugin reads work like this:

1. `@gloves/openclaw` registers plugin tools in the OpenClaw Gateway process.
2. `@gloves/openclaw` receives a `gloves_get` tool call.
3. `@gloves/mcp-client` launches a host-local `gloves-mcp` session over stdio by default.
4. `gloves-mcp` validates the session token and agent id.
5. `gloves-mcp` applies approval policy, returns redacted metadata, and delivers plaintext over the MCP secret side-channel.
6. The plugin injects the plaintext into `api.sandbox.env` or tmpfs.
7. The tool return value sent back to the model stays redacted.

This keeps the brokered tool-response model without requiring sandbox bind mounts for host binaries or unix sockets.

## Transport Choices

- OpenClaw default: plugin tools plus stdio child-process sessions to `gloves-mcp`
- Compatibility transport: optional unix socket mode when another runtime needs a long-lived local broker
- Direct host automation: loopback TCP `gloves daemon`

The transports serve different runtimes. OpenClaw should prefer stdio because it avoids exposing a reusable endpoint into the sandbox.

## Docker Verification

The repository Docker harness exercises the OpenClaw-style stdio flow:

1. the sandbox image includes `gloves` and `gloves-mcp`
2. the plugin starts `gloves-mcp` over stdio inside the container
3. decrypted values are injected into env/tmpfs and kept out of tool result bodies
4. cross-agent access and post-rotation access rules are verified end to end

## Rotation Flow

`gloves rotate --agent <id>` currently:

1. validates the current identity
2. generates a staged replacement identity
3. rewrites recipient references in `.age-recipients` files and `.gloves.yaml`
4. runs `updatekeys` with the old identity so existing ciphertext can still be decrypted
5. archives the old identity
6. promotes the staged identity into place

`gloves-mcp` exposes the same operation as `gloves_rotate` for the authenticated agent.

## Approval Model

The current MCP policy tiers are:

- auto: `gloves_list`, `gloves_show`, `gloves_approve`
- human/approval-gated: `gloves_get`, `gloves_set`, `gloves_rotate`
- deny: `gloves_delete`

When approval is required, the server creates a pending request and blocks until another authenticated MCP session resolves it or the request times out.

## Planned Next Steps

The long-form implementation spec still calls for:

- broader production-style end-to-end coverage for Gateway installs
- additional runtime adapters beyond OpenClaw

Those items are not yet the architecture on disk today, so they are tracked as future work rather than described here as completed behavior.