keypin 0.1.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 CHANGED
@@ -14,92 +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
 
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).
31
+
32
32
  ```sh
33
33
  bun add -g keypin
34
34
  ```
35
35
 
36
- ### From source
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.
38
+
39
+ ## Quick start
37
40
 
38
- With git and [Node](https://nodejs.org) 22.18+ (the installer runs on Node):
41
+ Register a project. `keypin init` writes a commented `keypin.toml` for you to fill in:
39
42
 
40
43
  ```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'
44
+ cd ~/code/my-project
45
+ keypin init
45
46
  ```
46
47
 
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.
48
+ A key looks like this:
49
49
 
50
- > [!IMPORTANT]
51
- > Run the install command again after every `git pull`, or keypin can't find its own packages.
50
+ ```toml
51
+ [vaults.personal]
52
+ kind = "1password"
53
+ account = "my.1password.com"
54
+ vault = "Private"
52
55
 
53
- ## Set up
56
+ [keys.api-token]
57
+ env = "API_TOKEN"
58
+ owner = "my-project"
54
59
 
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:**
60
+ [keys.api-token.dev] # read by keypin run
61
+ vault = "personal"
62
+ item = "my-project dev api token"
62
63
 
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
- ```
64
+ [keys.api-token.prod] # read by keypin publish
65
+ vault = "personal"
66
+ item = "my-project prod api token"
69
67
 
70
- ## Commands
71
-
72
- ```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
68
+ [[keys.api-token.prod.publish]] # where publish writes it
69
+ to = "github-actions"
70
+ repo = "me/my-project"
78
71
  ```
79
72
 
80
- `publish` writes `prod` by default (`--env dev` for dev). It checks each destination is the account the map pins,
81
- skips destinations that already have this value, and asks you to type `yes` before a first write or an account
82
- change. `--yes` never gives that approval.
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:
83
75
 
84
- Destinations: GitHub Actions secrets (with `gh`'s login) and Cloudflare Worker secrets (with wrangler's login).
85
-
86
- ## Notes
87
-
88
- - **Cloudflare Workers:** `wrangler dev` passes environment variables to the Worker only for names in
89
- `secrets.required`, and a `.dev.vars` file overrides them. Delete `.dev.vars`, then `keypin run -- wrangler dev`.
90
- - **macOS only for now:** the Cloudflare destination reads wrangler's login from its macOS path.
91
- - **Files on your machine:** the project registry (`~/.config/keypin/registry.json`) and receipts
92
- (`~/.local/state/keypin/state.json`). Both honor `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
+ ```
93
81
 
94
- ## Development
82
+ ## Commands
95
83
 
96
84
  ```sh
97
- bun run check # format, lint and type-check
98
- bun run test # tests
99
- 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
100
92
  ```
101
93
 
102
- Install with the command above, never a plain `bun install`: Bun 1.3 rewrites `bun.lock` in an older format.
103
-
104
- Releases: Release Please keeps a release PR open. On it, select **Approve workflows to run** so `check` runs, then
105
- 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.
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.