keypin 0.2.0 → 0.4.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 CHANGED
@@ -14,134 +14,96 @@
14
14
  </p>
15
15
 
16
16
  <p align="center">
17
- <img src="https://img.shields.io/badge/status-pre--release-8A5300" alt="Pre-release">
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 reads
23
- values from 1Password only while a command runs, and writes them nowhere on disk.
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
- ```sh
33
- bun add -g keypin
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
- git clone https://github.com/caiopizzol/keypin.git ~/keypin
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
- Add the alias to your shell profile. Package scripts don't load aliases, so call
48
- `bunx bun@1.4.4 ~/keypin/apps/cli/src/main.ts` in full there.
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
- ## Set up
39
+ ## Quick start
54
40
 
55
- 1. **1Password:** in Settings → Developer, under "Integrate with the 1Password SDKs", select **Integrate with other
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
- keypin init [folder] # register a project and write a keypin.toml template
74
- keypin unregister [folder] # stop listing a project; its keypin.toml stays
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
- `publish` writes `prod` by default (`--env dev` for dev). It checks each destination is the account the map pins,
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
- [keys.site-deploy.prod.issue]
94
- provider = "cloudflare-account-token"
95
- account = "<your Cloudflare account ID>"
96
- admin = "shared cloudflare token admin" # an item in the same vault, read only by rotate
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
- The first run:
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
- Store it in your vault as the `admin` item, with `rotated` and `rotate_every` like any other key. keypin never
125
- publishes it, and `run` never injects it.
126
-
127
- ## Notes
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
- ## Development
82
+ ## Commands
137
83
 
138
84
  ```sh
139
- bun run check # format, lint and type-check
140
- bun run test # tests
141
- bun run typecheck # tsc in every package
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
- Install with the command above, never a plain `bun install`: Bun 1.3 rewrites `bun.lock` in an older format.
145
-
146
- Releases: Release Please keeps a release PR open. On it, select **Approve workflows to run** so `check` runs, then
147
- merge it to tag, create the GitHub Release and publish to npm.
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. `keypin --help` lists the exit codes.
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.