keypin 0.0.0 → 0.2.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
@@ -75,6 +75,7 @@ keypin unregister [folder] # stop listing a project; its keypin.toml stays
75
75
  keypin status [--json] # every key, its rotation dates and receipts, then problems
76
76
  keypin run -- <command> # run a command with the project's dev keys in its environment
77
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
78
79
  ```
79
80
 
80
81
  `publish` writes `prod` by default (`--env dev` for dev). It checks each destination is the account the map pins,
@@ -83,13 +84,54 @@ change. `--yes` never gives that approval.
83
84
 
84
85
  Destinations: GitHub Actions secrets (with `gh`'s login) and Cloudflare Worker secrets (with wrangler's login).
85
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`:
91
+
92
+ ```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
97
+ ```
98
+
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.
123
+
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
+
86
127
  ## Notes
87
128
 
88
129
  - **Cloudflare Workers:** `wrangler dev` passes environment variables to the Worker only for names in
89
130
  `secrets.required`, and a `.dev.vars` file overrides them. Delete `.dev.vars`, then `keypin run -- wrangler dev`.
90
131
  - **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`.
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`.
93
135
 
94
136
  ## Development
95
137
 
@@ -1,6 +1,4 @@
1
1
  // @bun
2
- var __require = import.meta.require;
3
-
4
2
  // src/install.ts
5
3
  import { fileURLToPath } from "url";
6
4
 
@@ -30,4 +28,4 @@ function installProblem(error, repo = checkout()) {
30
28
  return `${name ? `the package ${name}` : "a package"} isn't installed; ${fix}`;
31
29
  }
32
30
 
33
- export { __require, messageOf, errorCode, installProblem };
31
+ export { messageOf, errorCode, installProblem };