2pass 2.1.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 135196a393e121fb8b71d5295fdedc19f3bccb24885ce81cf630be59d2b7c64e
4
- data.tar.gz: 7f5684e81780732115fcf6b9d5a071cfd1e8a05eaa48246e35f7fd3841a702ce
3
+ metadata.gz: f561bd05467c55981216fd9629058f1e7cda385f957a4c3cf302ed24ae8a8354
4
+ data.tar.gz: 1cbf298e0ef020bc741a291732a61c905f6ea26c4a19135c28c35ee1cf2a84b9
5
5
  SHA512:
6
- metadata.gz: e1c997e62173b57c596adf21c9636bfd7ed3417a5f0611d497db1caa486a18e113ad37b234bec8b3334fcea282c5f99f2ec9dbd1b4e328222b1439f281629586
7
- data.tar.gz: 9697b86fe839dc5d29f7786ab2e278986fbdb64bd2fc89e142f6e8bc812f919a66d3b57afcb97e71e099d806cc1411c56c12f5117facf6174ee780de71812b14
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 build the gem and install it.
31
+ Then install the gem:
32
32
 
33
33
  ```sh
34
- gem build 2pass.gemspec
35
- gem install 2pass-0.1.0.gem
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.