@coffre/cli 0.1.0 → 0.1.1

package/dist/main.js

@@ -5,6 +5,7 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { homedir, hostname } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
 //#region src/init.ts
 const KINDS = ["workers", "node"];
 /** Where a template lives: in the package when published, else in the repository. */
@@ -68,6 +69,67 @@ function init(kind, target, version) {
 	return written;
 }
 //#endregion
+//#region src/keys.ts
+/**
+* Three fresh keys, each 32 random bytes in base64, and an id for the KEK
+* dated to the day, so that a rotation, even one the same month, gets a new
+* one: the vault refuses two KEKs with the same id.
+*/
+function generateKeys(now = /* @__PURE__ */ new Date()) {
+	const key = () => randomBytes(32).toString("base64");
+	return {
+		KEK_ID: `kek-${now.toISOString().slice(0, 10)}`,
+		KEK: key(),
+		SIGNING_KEY: key(),
+		AUDIT_CHAIN_KEY: key()
+	};
+}
+/** The keys as a dotenv block, then, as comments, what each is for and where it goes. */
+function formatKeys(keys) {
+	return `KEK_ID=${keys.KEK_ID}
+KEK=${keys.KEK}
+SIGNING_KEY=${keys.SIGNING_KEY}
+AUDIT_CHAIN_KEY=${keys.AUDIT_CHAIN_KEY}
+
+# Save all four in your password manager now. They are shown once, and
+# coffre keeps no copy.
+#
+# The vault gets KEK_ID, KEK and SIGNING_KEY; the app gets AUDIT_CHAIN_KEY.
+# They are kept apart so that the app, which faces the network, never holds
+# what decrypts a value: whoever has the KEK and a copy of the database has
+# every value.
+#
+#   KEK              decrypts every value. Lose it, and every value is lost.
+#   SIGNING_KEY      signs the vault's log entries, checkpoints and member
+#                    rows. Lose it, and the log stops verifying and every
+#                    member is refused.
+#   AUDIT_CHAIN_KEY  signs the app's log entries, sessions and tokens. Lose
+#                    it, and the log stops verifying and everyone is signed
+#                    out.
+#   KEK_ID           names the KEK; not secret.
+#
+# On Workers, KEK_ID is a var in vault/wrangler.jsonc, and the other three are
+# Worker secrets (wrangler secret put). On Node, they go in vault.env and
+# server.env.
+#
+# These are for a new deployment. To rotate a deployment's KEK, take only
+# KEK_ID and KEK, and keep the old pair in previousKeks: its SIGNING_KEY and
+# AUDIT_CHAIN_KEY cannot be changed.
+`;
+}
+function keys(args) {
+	const { values } = parseArgs({
+		args,
+		options: { json: {
+			type: "boolean",
+			default: false
+		} },
+		allowPositionals: false
+	});
+	const fresh = generateKeys();
+	process.stdout.write(values.json ? `${JSON.stringify(fresh)}\n` : formatKeys(fresh));
+}
+//#endregion
 //#region src/instance.ts
 const MODES = ["signin", "cloudflare"];
 function emptyStore() {
@@ -1531,6 +1593,7 @@ const USAGE = `coffre - secrets, with an audit log
   New deployment
     coffre init --workers [<dir>]           two Cloudflare Workers: the app and its vault
     coffre init --node [<dir>]              a Node server, and its vault beside it
+    coffre keys [--json]                    its three keys and the KEK's id, made here and shown once
 
   Session
     coffre login [<url>] [--no-browser]     sign in, and make <url> the current instance
@@ -1579,6 +1642,9 @@ switch (command) {
 	case "init":
 		initProject(rest);
 		break;
+	case "keys":
+		keys(rest);
+		break;
 	case "login":
 		await login(rest);
 		break;

package/dist/templates/node/README.md

@@ -22,10 +22,25 @@ cp vault.env.example vault.env
 ```
 
 Fill both in: `PUBLIC_URL`, a GitHub OAuth app whose callback is
-`<PUBLIC_URL>/auth/callback/github`, `ROOT_ADMINS`, and three keys from
-`openssl rand -base64 32`. Escrow `KEK` and its `KEK_ID`, `SIGNING_KEY`, `AUDIT_CHAIN_KEY` and the OAuth
-client secret in a password manager. Without the KEK, stored values cannot
-be read; without the other keys, the existing log cannot be verified.
+`<PUBLIC_URL>/auth/callback/github`, `ROOT_ADMINS`, and the keys from
+
+```sh
+coffre keys
+```
+
+Run it with the CLI you ran `coffre init` with, or as
+`npx @coffre/cli keys`. It prints three keys and the KEK's id, once, and
+keeps no copy. Save its output in your password manager, with the OAuth
+client secret, before anything else. `KEK_ID`, `KEK` and `SIGNING_KEY` go in
+`vault.env`, and `AUDIT_CHAIN_KEY` in `server.env`, so that the server,
+which faces the network, never holds what decrypts a value:
+
+- `KEK` decrypts every value. Lose it, and every value is lost.
+- `SIGNING_KEY` signs the vault's log entries and member rows.
+- `AUDIT_CHAIN_KEY` signs the server's log entries, sessions and tokens.
+
+Lose either of the last two, and the log stops verifying and everyone is
+locked out.
 
 ## 2. The database
 

package/dist/templates/node/package.json

@@ -13,11 +13,11 @@
     "conformance": "coffre-conformance node"
   },
   "dependencies": {
-    "@coffre/server": "0.1.0",
-    "@coffre/vault": "0.1.0"
+    "@coffre/server": "0.1.1",
+    "@coffre/vault": "0.1.1"
   },
   "devDependencies": {
-    "@coffre/conformance": "0.1.0",
+    "@coffre/conformance": "0.1.1",
     "@types/node": "26.1.1",
     "typescript": "5.9.3"
   }

package/dist/templates/node/server.env.example

@@ -13,6 +13,6 @@ VAULT_SOCKET=vault.sock
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 
-# 32 random bytes, base64 (`openssl rand -base64 32`): keys the audit log's
-# hash chain.
+# From `coffre keys`, saved in your password manager first: signs the
+# server's log entries, sessions and tokens.
 AUDIT_CHAIN_KEY=

package/dist/templates/node/vault.env.example

@@ -5,11 +5,11 @@ VAULT_SOCKET=vault.sock
 # The server's Postgres database, as the vault's own login.
 DATABASE_URL=postgres://coffre_vault_runtime:CHANGE_ME@127.0.0.1:5432/coffre
 
-# The key-encryption key: 32 random bytes, base64 (`openssl rand -base64 32`),
-# and a name for it. A rotation gives the new one a new name.
+# From `coffre keys`, saved in your password manager first.
+# The key-encryption key, and its name. A rotation gives the new one a new name.
 KEK_ID=kek-1
 KEK=
-# 32 random bytes, base64: signs the audit checkpoints.
+# Signs the vault's log entries, checkpoints and member rows.
 SIGNING_KEY=
 
 # Comma-separated emails: the first people in, whom nobody can remove.

package/dist/templates/workers/README.md

@@ -17,7 +17,7 @@ Worker secrets. Everything below runs from this directory.
 - `app/wrangler.jsonc`: `PUBLIC_URL`, and `GITHUB_CLIENT_ID` from a GitHub
   OAuth app whose callback is `<PUBLIC_URL>/auth/callback/github`.
 - `vault/wrangler.jsonc`: `ROOT_ADMINS`, the emails of the first people in,
-  and `KEK_ID`, a name for the key-encryption key below.
+  and `KEK_ID`, which `coffre keys` gives you below.
 
 ## 2. The database
 
@@ -58,11 +58,26 @@ Put the ids they print under `hyperdrive`, the first in
 `pnpm migrate` again after every upgrade of `@coffre/server`, before
 deploying it.
 
-## 3. Secrets
+## 3. Keys
 
-Generate three separate keys with `openssl rand -base64 32` and save them
-in your password manager first. The commands below prompt for the saved
-values; save the GitHub client secret there too.
+```sh
+coffre keys
+```
+
+Run it with the CLI you ran `coffre init` with, or as
+`npx @coffre/cli keys`. It prints three keys and the KEK's id, once, and
+keeps no copy. Save its output in your password manager, with the GitHub
+client secret, before anything else. The vault gets `KEK` and `SIGNING_KEY`,
+and the app `AUDIT_CHAIN_KEY`, so that the app, which faces the network,
+never holds what decrypts a value:
+
+- `KEK` decrypts every value. Lose it, and every value is lost.
+- `SIGNING_KEY` signs the vault's log entries and member rows.
+- `AUDIT_CHAIN_KEY` signs the app's log entries, sessions and tokens.
+
+Lose either of the last two, and the log stops verifying and everyone is
+locked out. Put `KEK_ID` in `vault/wrangler.jsonc`, then set the secrets;
+each command prompts for the saved value:
 
 ```sh
 pnpm exec wrangler secret put KEK -c vault/wrangler.jsonc
@@ -71,9 +86,7 @@ pnpm exec wrangler secret put AUDIT_CHAIN_KEY -c app/wrangler.jsonc
 pnpm exec wrangler secret put GITHUB_CLIENT_SECRET -c app/wrangler.jsonc
 ```
 
-Escrow `KEK` with its `KEK_ID`, `SIGNING_KEY` and `AUDIT_CHAIN_KEY`.
-Without the KEK, stored values cannot be read; without the other keys, the
-existing log cannot be verified. Keep older KEKs after rotation too.
+Keep older KEKs after a rotation too: what they wrapped still needs them.
 
 ## 4. Deploy
 

package/dist/templates/workers/app/wrangler.jsonc

@@ -17,6 +17,7 @@
     "GITHUB_CLIENT_ID": "replace-with-your-client-id"
   },
   "secrets": {
+    // AUDIT_CHAIN_KEY is from `coffre keys`; the app never gets the vault's keys.
     "required": ["GITHUB_CLIENT_SECRET", "AUDIT_CHAIN_KEY"]
   },
   // `wrangler hyperdrive create coffre --caching-disabled --connection-string=<runtime login URL>`

package/dist/templates/workers/package.json

@@ -14,13 +14,13 @@
     "conformance": "coffre-conformance workers"
   },
   "dependencies": {
-    "@coffre/server": "0.1.0",
-    "@coffre/ui": "0.1.0",
-    "@coffre/vault": "0.1.0"
+    "@coffre/server": "0.1.1",
+    "@coffre/ui": "0.1.1",
+    "@coffre/vault": "0.1.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "5.20260920.1",
-    "@coffre/conformance": "0.1.0",
+    "@coffre/conformance": "0.1.1",
     "typescript": "5.9.3",
     "wrangler": "4.118.0"
   }

package/dist/templates/workers/vault/wrangler.jsonc

@@ -11,13 +11,13 @@
   "workers_dev": false,
   "observability": { "enabled": true },
   "vars": {
-    // Names the KEK below; a rotation gives the new one a new id.
+    // Names the KEK below: from `coffre keys`. A rotation gives the new one a new id.
     "KEK_ID": "kek-1",
     // Comma-separated emails: the first people in, whom nobody can remove.
     "ROOT_ADMINS": "you@example.com"
   },
   "secrets": {
-    // Each 32 random bytes, base64: `openssl rand -base64 32`.
+    // From `coffre keys`: wrangler secret put KEK, then SIGNING_KEY.
     "required": ["KEK", "SIGNING_KEY"]
   },
   // The app's database, as the vault's own login: `wrangler hyperdrive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The coffre command line: secrets in your shell, and `coffre init` for a new deployment.",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/client": "0.1.0",
-    "@coffre/core": "0.1.0"
+    "@coffre/core": "0.1.1",
+    "@coffre/client": "0.1.1"
   },
   "scripts": {
     "build": "tsdown && node scripts/copy-templates.ts",