2pass 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +421 -7
- data/bin/2pass +331 -6
- data/lib/2pass/approvals.rb +128 -0
- data/lib/2pass/broker.rb +462 -0
- data/lib/2pass/bundle.rb +289 -0
- data/lib/2pass/device.rb +207 -0
- data/lib/2pass/device_cache.rb +85 -0
- data/lib/2pass/device_registry.rb +131 -0
- data/lib/2pass/encryption.rb +277 -0
- data/lib/2pass/envelope.rb +323 -0
- data/lib/2pass/locked_json_file.rb +33 -0
- data/lib/2pass/policy.rb +128 -0
- data/lib/2pass/remote.rb +387 -0
- data/lib/2pass/replay_cache.rb +27 -0
- data/lib/2pass/server.rb +84 -0
- data/lib/2pass/version.rb +1 -1
- data/lib/2pass.rb +267 -18
- metadata +15 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: f561bd05467c55981216fd9629058f1e7cda385f957a4c3cf302ed24ae8a8354
|
|
4
|
+
data.tar.gz: 1cbf298e0ef020bc741a291732a61c905f6ea26c4a19135c28c35ee1cf2a84b9
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a9a9e607d459f90436f25c3c8ec7db2e9fae233ceb496f0affc01a81aaf4b72f4b0de3761179e8912c2f3df7965330ab17e07f845b2a9ce69abd1830b333d5c7
|
|
7
|
+
data.tar.gz: 9f04302ca7c962f2c97e97fc599833ba16e6e9623e7714a78b15f68d3a65dd79362ff340597c773d5d1c41286b208ffcef6c80dfedfafec4df1b935f62ab6aec
|
data/README.md
CHANGED
|
@@ -28,30 +28,444 @@ Alternatively, if you already have a vault file in a different location, you can
|
|
|
28
28
|
2pass link vault_name /path/to/vault_name.yml
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
Then
|
|
31
|
+
Then install the gem:
|
|
32
32
|
|
|
33
33
|
```sh
|
|
34
|
-
gem
|
|
35
|
-
|
|
34
|
+
gem install 2pass # released version
|
|
35
|
+
# or from a checkout (e.g. a branch under test):
|
|
36
|
+
bundle install && bundle exec rake install
|
|
37
|
+
mise reshim # if Ruby comes from mise
|
|
38
|
+
2pass -v
|
|
36
39
|
```
|
|
37
40
|
|
|
38
41
|
## Usage
|
|
39
42
|
|
|
40
43
|
```sh
|
|
41
|
-
2pass -h
|
|
44
|
+
2pass -h # every command and option
|
|
42
45
|
2pass get <vault_name> <id> [env]
|
|
43
|
-
2pass list <vault_name> [env]
|
|
44
|
-
2pass list <vault_name> [env] --json
|
|
45
|
-
2pass list <vault_name> [env] --dotenv
|
|
46
|
+
2pass list <vault_name> [env] [--json|--dotenv]
|
|
46
47
|
2pass add <vault_name> <id> <value> [env]
|
|
47
48
|
2pass link <vault_name> <target_path> [env]
|
|
48
49
|
2pass update
|
|
50
|
+
|
|
51
|
+
# sharing with other machines (see below)
|
|
52
|
+
2pass device init | id | approve | list | renew | revoke
|
|
53
|
+
2pass policy grant | show
|
|
54
|
+
2pass bundle export | import | source | status
|
|
55
|
+
2pass hub share | trust | list | remove | ping
|
|
56
|
+
2pass key init, 2pass migrate encrypt # encryption at rest
|
|
57
|
+
2pass broker, serve, use, approvals, approve, deny, cache clear
|
|
49
58
|
```
|
|
50
59
|
You can also pass an optional environment to most commands:
|
|
51
60
|
`2pass get myproject mykey production`
|
|
52
61
|
|
|
53
62
|
This will search for `mykey` within `myproject.production.yml`
|
|
54
63
|
|
|
64
|
+
## Encryption at rest
|
|
65
|
+
|
|
66
|
+
Vaults can be stored encrypted (AES-256-GCM) instead of as plaintext YAML.
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
2pass key init # master key in the macOS Keychain
|
|
70
|
+
2pass key init --key-store file # or ~/.2pass/master.key (0600), e.g. on Linux
|
|
71
|
+
2pass migrate encrypt myproject production
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
After `key init`, new vaults are created as `<vault>[.<env>].yml.enc`; `get`,
|
|
75
|
+
`list`, `add`, and the broker work unchanged. `migrate encrypt` converts an
|
|
76
|
+
existing vault, verifies it decrypts, then removes the local plaintext file (or
|
|
77
|
+
symlink; a symlink's target in iCloud/Dropbox is reported but never deleted).
|
|
78
|
+
Pass `--keep-plaintext` to keep the original during a transition.
|
|
79
|
+
|
|
80
|
+
Each encrypted file is bound to its vault name and env, so a file renamed or
|
|
81
|
+
copied to another vault/env is rejected. **Back up the master key**: without it,
|
|
82
|
+
encrypted vaults cannot be recovered. On macOS:
|
|
83
|
+
`security find-generic-password -s 2pass -a master-key -w`.
|
|
84
|
+
|
|
85
|
+
## Sealed bundles (no connection needed)
|
|
86
|
+
|
|
87
|
+
The simplest way to give a machine that has no access to your synced vaults
|
|
88
|
+
(say a laptop without your Apple ID) the secrets it needs. A **primary**
|
|
89
|
+
machine (one that has the vaults) packs what the laptop is granted, encrypts
|
|
90
|
+
it to the laptop's key and signs it. The result is text you can move over
|
|
91
|
+
**any** channel (Slack, email, Messages, AirDrop, USB): only the laptop can
|
|
92
|
+
open it and nobody can change it. Nothing listens, no SSH, no Tailscale.
|
|
93
|
+
|
|
94
|
+
### First time
|
|
95
|
+
|
|
96
|
+
1. **Both machines:** install 2pass (see [Getting started](#getting-started)).
|
|
97
|
+
2. **Laptop:** create its identity.
|
|
98
|
+
```sh
|
|
99
|
+
2pass device init --name laptop
|
|
100
|
+
```
|
|
101
|
+
It prints a pairing code and a pairing token (`2pass-device:...`). The
|
|
102
|
+
token isn't secret: send it to the primary. Run `2pass device id` to show
|
|
103
|
+
them again.
|
|
104
|
+
3. **Primary:** create its own identity (once per primary), then approve the
|
|
105
|
+
laptop.
|
|
106
|
+
```sh
|
|
107
|
+
2pass device init --name home
|
|
108
|
+
2pass device approve <laptop-token>
|
|
109
|
+
```
|
|
110
|
+
Check that the pairing code shown matches the laptop's, then pick which
|
|
111
|
+
vaults the laptop may read (`--grant potloc` or `--grant myproject:production`
|
|
112
|
+
answers without asking). The laptop is known by the name it was approved
|
|
113
|
+
under (`2pass device list`); use that name below.
|
|
114
|
+
4. **Primary:** export a bundle and send it.
|
|
115
|
+
```sh
|
|
116
|
+
2pass bundle export laptop | pbcopy
|
|
117
|
+
```
|
|
118
|
+
The terminal shows what went in (secret ids only, never values).
|
|
119
|
+
5. **Laptop:** import it.
|
|
120
|
+
```sh
|
|
121
|
+
2pass bundle import
|
|
122
|
+
```
|
|
123
|
+
Paste the bundle when asked; reading stops at its `-----END` line. Don't
|
|
124
|
+
paste it on the command line after `import`: the shell runs each line
|
|
125
|
+
separately. (`pbpaste | 2pass bundle import` also works.)
|
|
126
|
+
|
|
127
|
+
The first bundle from a primary shows that primary's pairing code: confirm
|
|
128
|
+
it matches `2pass device id` on the primary. From then on that primary is
|
|
129
|
+
trusted and isn't asked about again. A forged or damaged bundle is refused
|
|
130
|
+
before you're asked anything.
|
|
131
|
+
6. **Laptop:** use it, even offline.
|
|
132
|
+
```sh
|
|
133
|
+
2pass get potloc API_KEY # vault potloc.yml
|
|
134
|
+
2pass get myproject API_KEY production # vault myproject.production.yml
|
|
135
|
+
2pass list potloc --dotenv
|
|
136
|
+
2pass bundle status # what it holds (ids only), expiry
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### When secrets change, or before the bundle expires
|
|
140
|
+
|
|
141
|
+
Repeat steps 4 and 5. The laptop keeps the newest bundle and refuses older
|
|
142
|
+
ones.
|
|
143
|
+
|
|
144
|
+
To skip the copy/paste, export into a folder both machines can reach without
|
|
145
|
+
iCloud, such as a [Syncthing](https://syncthing.net) folder, a USB stick or a
|
|
146
|
+
private git repo:
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
2pass bundle export laptop --to ~/Sync/2pass-bundles # on a primary
|
|
150
|
+
2pass bundle source ~/Sync/2pass-bundles # on the laptop, once
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`get` and `list` then pick up newer bundles from that folder by themselves.
|
|
154
|
+
Automatic pickup only accepts bundles from primaries you already confirmed; for
|
|
155
|
+
a new primary, run `2pass bundle import --from <folder>` once in a terminal.
|
|
156
|
+
Each primary writes its own file (`laptop.home.2pass-bundle`), and the laptop
|
|
157
|
+
keeps the newest valid one. Keep that folder separate from iCloud Drive, and
|
|
158
|
+
never put vaults in it: only bundles.
|
|
159
|
+
|
|
160
|
+
### Managing what the laptop gets
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
2pass policy show # on a primary: who can read what
|
|
164
|
+
2pass policy grant laptop myproject:staging # add a vault (all its secrets)
|
|
165
|
+
2pass device revoke laptop # no more bundles for it
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Access lives in the primary's `~/.2pass/broker-policy.yml`. A grant without
|
|
169
|
+
`env` covers the base vault (`potloc.yml`); add one grant per env you want.
|
|
170
|
+
`device approve` adds a new device to that file and asks which vaults it may
|
|
171
|
+
read; `--grant VAULT[:ENV]` (repeatable) answers without asking, and `--yes`
|
|
172
|
+
alone gives an entry with no access. An existing entry is never changed, except
|
|
173
|
+
to add what `--grant` lists. Grants added this way cover all secrets of the
|
|
174
|
+
vault with `get`/`list`; edit the file for anything narrower (specific `ids`,
|
|
175
|
+
`require_approval`). Rewriting the file drops YAML comments; the previous
|
|
176
|
+
version is kept as `broker-policy.yml.bak`.
|
|
177
|
+
|
|
178
|
+
What to know:
|
|
179
|
+
|
|
180
|
+
- A bundle holds the laptop's grants that allow `get`/`list` with
|
|
181
|
+
`allow_reveal`, for every purpose. Grants with `require_approval` are never
|
|
182
|
+
bundled.
|
|
183
|
+
- It expires after 14 days by default (`--expires-in DAYS`), never later than
|
|
184
|
+
the laptop's own approval. The laptop refuses expired bundles and bundles
|
|
185
|
+
older than the one it has.
|
|
186
|
+
- A delivered bundle can't be recalled. If the laptop is lost, revoke it and
|
|
187
|
+
rotate the secrets `bundle export` listed. Keep bundles narrow and short.
|
|
188
|
+
- The laptop is read-only: `add` happens on a primary. If the laptop also
|
|
189
|
+
trusts a primary with `--ssh`, it asks that primary first and uses the
|
|
190
|
+
bundle when no primary is reachable.
|
|
191
|
+
|
|
192
|
+
## Hub and devices (live access over SSH)
|
|
193
|
+
|
|
194
|
+
Most setups only need [sealed bundles](#sealed-bundles-no-connection-needed).
|
|
195
|
+
Use a hub when a device must always get fresh answers, have access revoked
|
|
196
|
+
immediately, or ask for per-request approval; it needs SSH access to the
|
|
197
|
+
primary.
|
|
198
|
+
|
|
199
|
+
Instead of syncing vault files (iCloud, Dropbox), one always-on machine, the
|
|
200
|
+
**hub**, keeps the encrypted vaults. Other machines (**devices**) ask it for
|
|
201
|
+
secrets with signed, encrypted requests. Only approved devices get answers,
|
|
202
|
+
and only for what `broker-policy.yml` grants them.
|
|
203
|
+
|
|
204
|
+
### 1. Set up the hub
|
|
205
|
+
|
|
206
|
+
```sh
|
|
207
|
+
2pass key init # encrypt vaults at rest
|
|
208
|
+
2pass migrate encrypt myproject production
|
|
209
|
+
2pass device init --name hub # the hub's own identity
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### 2. Pair a device
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
# on the device
|
|
216
|
+
2pass device init --name work-laptop # prints a pairing code + token
|
|
217
|
+
|
|
218
|
+
# on the hub
|
|
219
|
+
2pass device approve <device-token> # compare the pairing code, confirm
|
|
220
|
+
# -> prints the hub's token and the command to run on the device
|
|
221
|
+
|
|
222
|
+
# on the device
|
|
223
|
+
2pass hub trust <hub-token> --ssh 2pass-hub # compare the hub's code, confirm
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
`--ssh` takes anything `ssh` accepts. Use a dedicated alias in the device's
|
|
227
|
+
`~/.ssh/config`, so the address, user and key live in one standard place and
|
|
228
|
+
moving the hub only means editing that file:
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
Host 2pass-hub
|
|
232
|
+
HostName hub.your-tailnet.ts.net # or an IP / LAN name
|
|
233
|
+
User me
|
|
234
|
+
IdentityFile ~/.ssh/2pass_ed25519 # dedicated key, see "Locking down SSH"
|
|
235
|
+
IdentitiesOnly yes
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
The name is only routing: the device trusts the hub's pinned keys, so a wrong
|
|
239
|
+
or hijacked address gets replies rejected, not secrets leaked.
|
|
240
|
+
|
|
241
|
+
Always compare pairing codes on both machines: that is what proves the tokens
|
|
242
|
+
were not swapped in transit. Approvals expire after 90 days by default
|
|
243
|
+
(`--expires-in DAYS|never`); manage them with `2pass device list|renew|revoke`.
|
|
244
|
+
Revoked keys stay listed and can never be re-approved.
|
|
245
|
+
|
|
246
|
+
### 3. Grant access on the hub
|
|
247
|
+
|
|
248
|
+
A new device can do nothing until `~/.2pass/broker-policy.yml` names it as an
|
|
249
|
+
actor (see [Local broker](#local-broker-for-agent-access)):
|
|
250
|
+
|
|
251
|
+
```yaml
|
|
252
|
+
actors:
|
|
253
|
+
work-laptop:
|
|
254
|
+
grants:
|
|
255
|
+
- vault: myproject
|
|
256
|
+
env: production
|
|
257
|
+
ids: "*"
|
|
258
|
+
operations: [get, list]
|
|
259
|
+
purposes: [cli]
|
|
260
|
+
allow_reveal: true
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### 4. Use it
|
|
264
|
+
|
|
265
|
+
On a device that trusts a hub, `get` and `list` read from the hub
|
|
266
|
+
(`--purpose` defaults to `cli`); `add` must be run on the hub.
|
|
267
|
+
|
|
268
|
+
```sh
|
|
269
|
+
2pass hub ping
|
|
270
|
+
2pass get myproject API_KEY production
|
|
271
|
+
2pass list myproject production --dotenv
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Several primary machines
|
|
275
|
+
|
|
276
|
+
If you have more than one main machine (say `home` and `work`, which you don't
|
|
277
|
+
use at the same time), each can act as a hub. They keep sharing the vaults
|
|
278
|
+
through a synced folder such as iCloud Drive, as before; only the laptop needs
|
|
279
|
+
to trust them.
|
|
280
|
+
|
|
281
|
+
```sh
|
|
282
|
+
# on each primary machine (once)
|
|
283
|
+
2pass device init --name home # "work" on the other one
|
|
284
|
+
2pass hub share ~/Library/Mobile\ Documents/com~apple~CloudDocs/2pass
|
|
285
|
+
|
|
286
|
+
# on the laptop: trust each primary
|
|
287
|
+
2pass hub trust <home-token> --ssh 2pass-home
|
|
288
|
+
2pass hub trust <work-token> --ssh 2pass-work
|
|
289
|
+
2pass hub list
|
|
290
|
+
2pass hub ping # one line per primary
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
- On the primaries nothing changes day to day: `get`, `list`, `add` and `link`
|
|
294
|
+
still read the synced files directly. `hub share` makes vaults (new ones are
|
|
295
|
+
created there), `devices.yml` and `broker-policy.yml` live in the shared
|
|
296
|
+
folder, so approving or revoking the laptop on one primary applies to all.
|
|
297
|
+
Keys, the approvals queue and the replay cache stay local to each machine.
|
|
298
|
+
- The laptop asks the primary that answered last, then the others (5 s SSH
|
|
299
|
+
connect timeout). It only moves on when a primary is **unreachable**; a
|
|
300
|
+
primary that refuses (not authorized, revoked, waiting for approval) is
|
|
301
|
+
final, so a refusal can't be bypassed through another machine. Approve a
|
|
302
|
+
pending request on the primary that received it.
|
|
303
|
+
- Revocation reaches the other primaries as fast as the folder syncs.
|
|
304
|
+
- macOS: `serve` runs over SSH, which cannot read iCloud Drive until you enable
|
|
305
|
+
**System Settings > General > Sharing > Remote Login (i) > Allow full disk
|
|
306
|
+
access for remote users** on each primary.
|
|
307
|
+
- With plain YAML vaults, whoever can write to the synced folder can already
|
|
308
|
+
read your secrets, so the shared `devices.yml` and policy need no extra
|
|
309
|
+
protection. If you later turn on vault encryption, they will need signing;
|
|
310
|
+
until then `hub share` warns about it.
|
|
311
|
+
|
|
312
|
+
### Agents
|
|
313
|
+
|
|
314
|
+
An agent on a device acts under its own name: `--agent claude` or
|
|
315
|
+
`TWOPASS_AGENT=claude`. The hub sees `work-laptop/claude`, which needs its own
|
|
316
|
+
grants; it does not inherit the device's.
|
|
317
|
+
|
|
318
|
+
```yaml
|
|
319
|
+
actors:
|
|
320
|
+
work-laptop/claude:
|
|
321
|
+
grants:
|
|
322
|
+
- vault: myproject
|
|
323
|
+
env: production
|
|
324
|
+
ids: [DEPLOY_TOKEN]
|
|
325
|
+
operations: [use]
|
|
326
|
+
purposes: [deploy]
|
|
327
|
+
require_approval: true
|
|
328
|
+
actions:
|
|
329
|
+
deploy:
|
|
330
|
+
command: [bin/deploy]
|
|
331
|
+
env: {DEPLOY_TOKEN: DEPLOY_TOKEN}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
```sh
|
|
335
|
+
TWOPASS_AGENT=claude 2pass use myproject deploy production --purpose deploy
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
`use` runs the action **on the hub**; only its output (with secret values
|
|
339
|
+
redacted) comes back, so the agent never sees the token.
|
|
340
|
+
|
|
341
|
+
The agent name is a label chosen by the device. It scopes grants, approvals
|
|
342
|
+
and the cache, but it does not stop code running as the same OS user from
|
|
343
|
+
using the device's own name. For a hard boundary, run the agent as a separate
|
|
344
|
+
OS user with its own `2pass device init`.
|
|
345
|
+
|
|
346
|
+
### Approvals
|
|
347
|
+
|
|
348
|
+
Grants with `require_approval: true` make the hub queue the request:
|
|
349
|
+
|
|
350
|
+
```sh
|
|
351
|
+
# on the hub
|
|
352
|
+
2pass approvals # who, what, which vault/secret, purpose
|
|
353
|
+
2pass approve 3f9a1c2e # or: --for 30 (minutes)
|
|
354
|
+
2pass deny 3f9a1c2e
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
An approval covers that exact caller + operation + secret (or action) +
|
|
358
|
+
vault/env + purpose for `approval_ttl` seconds (default 600), so it isn't
|
|
359
|
+
asked again on every call. Meanwhile the device waits and retries for up to
|
|
360
|
+
`--wait` seconds (default 120; `--wait 0` fails immediately with the approval
|
|
361
|
+
id). Unanswered requests lapse after 10 minutes.
|
|
362
|
+
|
|
363
|
+
### Caching on the device
|
|
364
|
+
|
|
365
|
+
Answers to `get` and `list` are cached on the device for the grant's
|
|
366
|
+
`cache_ttl` seconds (default 300; `0` disables), capped by the remaining
|
|
367
|
+
approval window and the device's own approval expiry. Repeated calls skip the
|
|
368
|
+
hub and keep working if it is briefly unreachable.
|
|
369
|
+
|
|
370
|
+
The cache (`~/.2pass/cache/`) is encrypted with a key derived from the device's
|
|
371
|
+
private key, and file names reveal nothing. It is wiped as soon as the hub
|
|
372
|
+
reports the device as revoked or expired. `--no-cache` bypasses it and
|
|
373
|
+
`2pass cache clear` deletes it. Revocation therefore takes effect on the hub
|
|
374
|
+
immediately, and on a device at the latest when its cached answers expire;
|
|
375
|
+
keep `cache_ttl` short (or `0`) for sensitive grants.
|
|
376
|
+
|
|
377
|
+
### Grant options
|
|
378
|
+
|
|
379
|
+
| Field | Meaning |
|
|
380
|
+
|---|---|
|
|
381
|
+
| `vault`, `env`, `ids`, `purposes`, `operations` | what is allowed (`ids: "*"` for all) |
|
|
382
|
+
| `allow_reveal` | required for `get` and `list` |
|
|
383
|
+
| `actions` | named commands for `use` (run on the hub) |
|
|
384
|
+
| `expires_at` | ISO8601 end of the grant |
|
|
385
|
+
| `require_approval` | queue requests for `2pass approve` |
|
|
386
|
+
| `approval_ttl` | seconds an approval is reused (default 600) |
|
|
387
|
+
| `cache_ttl` | seconds a device may cache answers (default 300, `0` = never) |
|
|
388
|
+
|
|
389
|
+
### Locking down SSH on the hub
|
|
390
|
+
|
|
391
|
+
The hub runs `2pass serve --stdio` once per request. Give each device a
|
|
392
|
+
dedicated key (`ssh-keygen -t ed25519 -f ~/.ssh/2pass_ed25519`), referenced by
|
|
393
|
+
the `2pass-hub` alias above, and pin it to that command in the hub's `~/.ssh/authorized_keys`, so the key can do
|
|
394
|
+
nothing else (use an absolute path; non-interactive SSH has a minimal `PATH`):
|
|
395
|
+
|
|
396
|
+
```
|
|
397
|
+
command="/absolute/path/to/2pass serve --stdio",restrict ssh-ed25519 AAAA... work-laptop
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
SSH only carries the bytes. Access is decided by the 2pass signature on each
|
|
401
|
+
request, checked against `devices.yml`, so a leaked SSH key alone gets nothing.
|
|
402
|
+
Requests older than 60 seconds or seen before are rejected; replies are
|
|
403
|
+
encrypted to a one-time key, so recorded traffic stays unreadable.
|
|
404
|
+
|
|
405
|
+
## Local broker for agent access
|
|
406
|
+
|
|
407
|
+
Use `2pass broker` when an external actor, such as an AI agent, needs narrow
|
|
408
|
+
on-demand access. The broker reads one JSON request from stdin, reloads its YAML
|
|
409
|
+
policy for that request, and returns JSON. It does not expose `add`, `link`,
|
|
410
|
+
`save`, or `update`.
|
|
411
|
+
|
|
412
|
+
For a stronger boundary, run the broker as a dedicated local user with read-only
|
|
413
|
+
access to the vault files. The broker code is read-only, but OS permissions are
|
|
414
|
+
the reliable way to prevent writes if a configured action runs another process.
|
|
415
|
+
|
|
416
|
+
Example policy:
|
|
417
|
+
|
|
418
|
+
```yaml
|
|
419
|
+
actors:
|
|
420
|
+
agent:
|
|
421
|
+
grants:
|
|
422
|
+
- vault: myproject
|
|
423
|
+
env: production
|
|
424
|
+
ids:
|
|
425
|
+
- API_KEY
|
|
426
|
+
operations:
|
|
427
|
+
- list_ids
|
|
428
|
+
- metadata
|
|
429
|
+
- use
|
|
430
|
+
purposes:
|
|
431
|
+
- deploy
|
|
432
|
+
expires_at: "2030-01-01T00:00:00Z"
|
|
433
|
+
actions:
|
|
434
|
+
check-status:
|
|
435
|
+
command:
|
|
436
|
+
- ruby
|
|
437
|
+
- -e
|
|
438
|
+
- "puts ENV.fetch('API_TOKEN').empty? ? 'missing' : 'present'"
|
|
439
|
+
env:
|
|
440
|
+
API_TOKEN: API_KEY
|
|
441
|
+
timeout: 5
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
Example request:
|
|
445
|
+
|
|
446
|
+
```sh
|
|
447
|
+
printf '%s' '{"actor":"agent","operation":"list_ids","vault":"myproject","env":"production","purpose":"deploy"}' \
|
|
448
|
+
| 2pass broker --policy ~/.2pass/broker-policy.yml
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
Supported broker operations:
|
|
452
|
+
|
|
453
|
+
- `list_ids`: returns only authorized secret IDs, never values.
|
|
454
|
+
- `metadata`: reports whether an authorized secret exists, without its value.
|
|
455
|
+
- `use`: runs a policy-defined command with authorized secrets injected as
|
|
456
|
+
environment variables; secret values are redacted from stdout and stderr.
|
|
457
|
+
- `get`: returns a raw value only when the grant includes `operations: ["get"]`
|
|
458
|
+
and `allow_reveal: true`.
|
|
459
|
+
- `list`: returns id/value pairs for every secret allowed by grants with
|
|
460
|
+
`operations: ["list"]` and `allow_reveal: true`.
|
|
461
|
+
|
|
462
|
+
When requests arrive from a device through the hub, the actor is always the
|
|
463
|
+
verified device name; any `actor` field in the request is ignored.
|
|
464
|
+
|
|
465
|
+
Add `expires_at` to grants when access should be temporary. The broker reloads
|
|
466
|
+
the policy on every request, so removing or expiring a grant takes effect on the
|
|
467
|
+
next call.
|
|
468
|
+
|
|
55
469
|
## Development
|
|
56
470
|
|
|
57
471
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|