keypin 0.2.0 → 0.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.
- package/README.md +66 -104
- package/{chunk-mjxb8yj8.js → chunk-p51dggc1.js} +945 -54
- package/main.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -14,134 +14,96 @@
|
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
16
|
<p align="center">
|
|
17
|
-
<img src="https://img.shields.io/
|
|
17
|
+
<a href="https://www.npmjs.com/package/keypin"><img src="https://img.shields.io/npm/v/keypin?color=121311" alt="npm version"></a>
|
|
18
18
|
<img src="https://img.shields.io/badge/license-MIT-121311" alt="MIT">
|
|
19
19
|
<img src="https://img.shields.io/badge/runtime-Bun-121311" alt="Bun">
|
|
20
20
|
</p>
|
|
21
21
|
|
|
22
|
-
Each project lists its keys in a `keypin.toml`: names, vault items and destinations, never values. keypin
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
## Requirements
|
|
26
|
-
|
|
27
|
-
- [Bun](https://bun.sh) 1.4.4 or newer. keypin refuses an older one, because Bun 1.3.12 misparses some TOML.
|
|
28
|
-
- The [1Password](https://1password.com/downloads) desktop app
|
|
22
|
+
Each project lists its keys in a `keypin.toml`: names, vault items and destinations, never values. keypin runs your
|
|
23
|
+
commands with dev keys, publishes keys to GitHub Actions and Cloudflare Workers, and rotates Cloudflare API tokens.
|
|
24
|
+
It reads values from 1Password only while a command runs, and never writes them to disk.
|
|
29
25
|
|
|
30
26
|
## Install
|
|
31
27
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
### From source
|
|
37
|
-
|
|
38
|
-
With git and [Node](https://nodejs.org) 22.18+ (the installer runs on Node):
|
|
28
|
+
You need [Bun](https://bun.sh) 1.4.4 or newer and the [1Password](https://1password.com/downloads) desktop app.
|
|
29
|
+
To publish, you also need a [`gh`](https://cli.github.com) login for GitHub, or a
|
|
30
|
+
[`wrangler`](https://developers.cloudflare.com/workers/wrangler/) login for Cloudflare (macOS only for now).
|
|
39
31
|
|
|
40
32
|
```sh
|
|
41
|
-
|
|
42
|
-
cd ~/keypin
|
|
43
|
-
bunx --package vite-plus@1.5.1 vp install
|
|
44
|
-
alias keypin='bunx bun@1.4.4 ~/keypin/apps/cli/src/main.ts'
|
|
33
|
+
bun add -g keypin
|
|
45
34
|
```
|
|
46
35
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
> [!IMPORTANT]
|
|
51
|
-
> Run the install command again after every `git pull`, or keypin can't find its own packages.
|
|
36
|
+
In 1Password, open **Settings → Developer**. Under **Integrate with the 1Password SDKs**, select **Integrate with
|
|
37
|
+
other apps**. 1Password then asks you to approve each keypin command.
|
|
52
38
|
|
|
53
|
-
##
|
|
39
|
+
## Quick start
|
|
54
40
|
|
|
55
|
-
|
|
56
|
-
apps**. 1Password then asks you to approve each keypin command.
|
|
57
|
-
2. **Each vault item** needs:
|
|
58
|
-
- the value in its `password` field;
|
|
59
|
-
- a Date field `rotated`: the day the value last changed;
|
|
60
|
-
- a Text field `rotate_every`: `<n>d`, `<n>w`, `<n>m` or `never` (or set it in `keypin.toml`).
|
|
61
|
-
3. **Each project:**
|
|
62
|
-
|
|
63
|
-
```sh
|
|
64
|
-
cd ~/code/my-project
|
|
65
|
-
keypin init # registers the folder and writes a commented keypin.toml
|
|
66
|
-
$EDITOR keypin.toml
|
|
67
|
-
keypin status # exit 0 means no problems
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Commands
|
|
41
|
+
Register a project. `keypin init` writes a commented `keypin.toml` for you to fill in:
|
|
71
42
|
|
|
72
43
|
```sh
|
|
73
|
-
|
|
74
|
-
keypin
|
|
75
|
-
keypin status [--json] # every key, its rotation dates and receipts, then problems
|
|
76
|
-
keypin run -- <command> # run a command with the project's dev keys in its environment
|
|
77
|
-
keypin publish <key-id> # check accounts, show the plan, then write the key to every destination
|
|
78
|
-
keypin rotate <key-id> # replace a token with a new one, publish it, then revoke the old one
|
|
44
|
+
cd ~/code/my-project
|
|
45
|
+
keypin init
|
|
79
46
|
```
|
|
80
47
|
|
|
81
|
-
|
|
82
|
-
skips destinations that already have this value, and asks you to type `yes` before a first write or an account
|
|
83
|
-
change. `--yes` never gives that approval.
|
|
84
|
-
|
|
85
|
-
Destinations: GitHub Actions secrets (with `gh`'s login) and Cloudflare Worker secrets (with wrangler's login).
|
|
86
|
-
|
|
87
|
-
## Rotate
|
|
88
|
-
|
|
89
|
-
`rotate` replaces a Cloudflare account API token with a new one that has the same permissions. It needs an `issue`
|
|
90
|
-
section on the key's environment, at least one destination, and a `rotate_every` other than `never`:
|
|
48
|
+
A key looks like this:
|
|
91
49
|
|
|
92
50
|
```toml
|
|
93
|
-
[
|
|
94
|
-
|
|
95
|
-
account = "
|
|
96
|
-
|
|
51
|
+
[vaults.personal]
|
|
52
|
+
kind = "1password"
|
|
53
|
+
account = "my.1password.com"
|
|
54
|
+
vault = "Private"
|
|
55
|
+
|
|
56
|
+
[keys.api-token]
|
|
57
|
+
env = "API_TOKEN"
|
|
58
|
+
owner = "my-project"
|
|
59
|
+
|
|
60
|
+
[keys.api-token.dev] # read by keypin run
|
|
61
|
+
vault = "personal"
|
|
62
|
+
item = "my-project dev api token"
|
|
63
|
+
|
|
64
|
+
[keys.api-token.prod] # read by keypin publish
|
|
65
|
+
vault = "personal"
|
|
66
|
+
item = "my-project prod api token"
|
|
67
|
+
|
|
68
|
+
[[keys.api-token.prod.publish]] # where publish writes it
|
|
69
|
+
to = "github-actions"
|
|
70
|
+
repo = "me/my-project"
|
|
97
71
|
```
|
|
98
72
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
1. reads the current value and asks Cloudflare which token it is;
|
|
102
|
-
2. reads that token's policies with the admin token, and shows the plan: both tokens, the policies it copies, the
|
|
103
|
-
item and every destination. Type `yes`, or pass `--yes` when no destination needs approval;
|
|
104
|
-
3. makes a new token with the same policies, named after the old one plus today's date. It expires after the
|
|
105
|
-
key's `rotate_every` plus 14 days, so `status` shows it due well before it stops working;
|
|
106
|
-
4. checks the new token is active and has the same policies, or deletes it and stops;
|
|
107
|
-
5. stores it in the item with `rotated` set to today, and publishes it like `publish`.
|
|
108
|
-
|
|
109
|
-
The old token stays active. Check that everything that uses the key works, then run `keypin rotate <key-id>`
|
|
110
|
-
again: it checks every destination has the new value, shows when the old token was last used, and revokes it after
|
|
111
|
-
you type `yes`. `--yes` never revokes.
|
|
112
|
-
|
|
113
|
-
If a run stops, the next one continues or cleans up. `status` shows an unfinished rotation as a notice.
|
|
114
|
-
|
|
115
|
-
### The admin token
|
|
116
|
-
|
|
117
|
-
In the Cloudflare dashboard, go to **Manage account** → **Account API tokens** → **Create Token** → **Custom
|
|
118
|
-
token**:
|
|
119
|
-
|
|
120
|
-
- Permissions: **Account** → **Account API Tokens** → **Edit**, and nothing else;
|
|
121
|
-
- the account the keys live in;
|
|
122
|
-
- a short expiry, such as 30 days.
|
|
73
|
+
In 1Password, each item holds the value in its `password` field, plus a `rotated` date and a `rotate_every` period
|
|
74
|
+
such as `90d`. Now use it:
|
|
123
75
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
- **Cloudflare Workers:** `wrangler dev` passes environment variables to the Worker only for names in
|
|
130
|
-
`secrets.required`, and a `.dev.vars` file overrides them. Delete `.dev.vars`, then `keypin run -- wrangler dev`.
|
|
131
|
-
- **macOS only for now:** the Cloudflare destination reads wrangler's login from its macOS path.
|
|
132
|
-
- **Files on your machine:** the project registry (`~/.config/keypin/registry.json`), receipts
|
|
133
|
-
(`~/.local/state/keypin/state.json`) and rotations (`~/.local/state/keypin/rotations.json`). They honor
|
|
134
|
-
`XDG_CONFIG_HOME` and `XDG_STATE_HOME`.
|
|
76
|
+
```sh
|
|
77
|
+
keypin status # every key, when it's due, and any problem
|
|
78
|
+
keypin run -- npm run dev # run a command with the dev keys
|
|
79
|
+
keypin publish api-token # write the prod value to the GitHub secret
|
|
80
|
+
```
|
|
135
81
|
|
|
136
|
-
##
|
|
82
|
+
## Commands
|
|
137
83
|
|
|
138
84
|
```sh
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
85
|
+
keypin init [folder] # register a project and write a keypin.toml
|
|
86
|
+
keypin unregister [folder] # stop listing a project (its keypin.toml stays)
|
|
87
|
+
keypin status [--json] # every key, when it's due, and any problem
|
|
88
|
+
keypin discover [folder] # every key name a project uses, where it's set, and a draft map
|
|
89
|
+
keypin run -- <command> # run a command with the project's dev keys
|
|
90
|
+
keypin publish <key-id> # check each destination's account, then write the key
|
|
91
|
+
keypin rotate <key-id> # replace a Cloudflare API token, then revoke the old one
|
|
142
92
|
```
|
|
143
93
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
94
|
+
`publish` and `rotate` show a plan and wait for you to type `yes`. `--yes` skips that only for routine updates. It
|
|
95
|
+
never approves a first write, a changed account or vault item, or a revoke.
|
|
96
|
+
|
|
97
|
+
## Docs
|
|
98
|
+
|
|
99
|
+
- [Configuration](https://github.com/caiopizzol/keypin/blob/main/docs/configuration.md): every field in
|
|
100
|
+
`keypin.toml` and in the vault items.
|
|
101
|
+
- [Discover](https://github.com/caiopizzol/keypin/blob/main/docs/discover.md): what `discover` reads, the problems
|
|
102
|
+
it reports, and its draft map.
|
|
103
|
+
- [Publishing](https://github.com/caiopizzol/keypin/blob/main/docs/publishing.md): destinations, account checks and
|
|
104
|
+
approvals.
|
|
105
|
+
- [Rotation](https://github.com/caiopizzol/keypin/blob/main/docs/rotation.md): how `rotate` works, and the admin
|
|
106
|
+
token it needs.
|
|
107
|
+
- [Notes](https://github.com/caiopizzol/keypin/blob/main/docs/notes.md): `wrangler dev`, and the files keypin keeps.
|
|
108
|
+
- [Development](https://github.com/caiopizzol/keypin/blob/main/docs/development.md): install from source, checks and
|
|
109
|
+
releases.
|