@coffre/cli 0.1.1 → 0.1.3

package/dist/templates/node/README.md

@@ -9,7 +9,7 @@ Two processes, configured in code:
   only the server, on a Unix socket.
 
 Run them as two users that share a group, and the process facing the network
-never holds the KEK. For local development, `server.ts` can run the vault
+never holds the vault key. For local development, `server.ts` can run the vault
 in its own process instead; see the comment there. Everything below runs
 from this directory, on Node 24 or later.
 
@@ -19,63 +19,56 @@ from this directory, on Node 24 or later.
 pnpm install
 cp server.env.example server.env
 cp vault.env.example vault.env
+chmod 600 server.env vault.env
 ```
 
-Fill both in: `PUBLIC_URL`, a GitHub OAuth app whose callback is
-`<PUBLIC_URL>/auth/callback/github`, `ROOT_ADMINS`, and the keys from
+Fill in `PUBLIC_URL`, a GitHub OAuth app whose callback is
+`<PUBLIC_URL>/auth/callback/github`, and `ROOT_ADMINS`. Keep each env file
+readable only by its process's user.
 
-```sh
-coffre keys
-```
+## 2. The database and 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
-
-Use one Postgres database with three logins: its owner for migrations,
-`coffre_runtime` for the server, and `coffre_vault_runtime` for the vault.
-As an administrator, connect to the database with `psql` and create the
-runtime logins. `\password` prompts for each password without putting it
-in a SQL statement or shell history:
-
-```sql
-CREATE ROLE coffre_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-CREATE ROLE coffre_vault_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-\password coffre_runtime
-\password coffre_vault_runtime
-```
-
-Migrate as the owner, who must also be able to create and grant roles:
+Make a Postgres database, then:
 
 ```sh
-pnpm migrate "postgres://owner:…@db.example.com:5432/coffre"
+npx @coffre/cli setup
 ```
 
-The migration creates the `coffre_app` and `coffre_vault` group roles and
-grants each login only its group's rights. Only the vault writes members
-and grants; each login appends to the audit log only as itself. Run the
-migration again after every package upgrade, before starting either process.
-
-Fill `DATABASE_URL` in each env file with the same host and database, using
-`coffre_runtime` in `server.env` and `coffre_vault_runtime` in `vault.env`.
-URL-encode special characters in passwords. Neither process gets the owner's
-URL. Keep each env file readable only by its process's user (`chmod 600`).
+Run it with the CLI you ran `coffre init` with. It asks for the database
+administrator's connection string at a hidden prompt. A script can pipe it
+in, or set `COFFRE_SETUP_DATABASE_URL`; never pass it as an argument. It
+makes the two logins coffre runs as, `coffre_runtime` for the server and
+`coffre_vault_runtime` for the vault, migrates the database, and checks that
+each login holds only its rights.
+
+Then it shows five values on a screen of their own, which leaves nothing
+behind in your scrollback. Copy each with `c` into your password manager,
+beside the OAuth client secret, then into its file; `w` shows where each
+goes. Nothing keeps a copy. There is one key for each process, so that the
+server, which faces the network, never holds what decrypts a value.
+
+- `server.env` takes the app key, `APP_KEY`, and the app's database URL, as
+  `DATABASE_URL`. The app key signs the server's log entries, sessions and
+  tokens. Lose it, and everyone is signed out and the log stops verifying.
+- `vault.env` takes the vault ID, `VAULT_KEY_ID`, the vault key, `VAULT_KEY`,
+  and the vault's database URL, as `DATABASE_URL`. The vault key decrypts
+  every value, and the vault derives from it the key it signs its records
+  with. Lose it, and every value is lost. The vault ID only names it.
+- Both URLs are the same database, each through its process's own login.
+  Neither process gets the administrator's URL.
+
+With AWS KMS instead of a key of your own, the vault also needs a
+`SIGNING_KEY` ([keys](https://github.com/erwinkn/coffre/blob/main/docs/keys.md#aws-kms)).
+To do the same by hand, see
+[deploy.md](https://github.com/erwinkn/coffre/blob/main/docs/deploy.md#appendix-the-database-by-hand).
+
+Run `pnpm migrate`, with the administrator's URL in `DATABASE_URL`, after
+every package upgrade, before starting either process.
 
 For tests and local development only, both URLs may instead name the same
-absolute SQLite file, e.g. `file:/tmp/coffre-local.db`; migrate that URL once.
-SQLite has no database logins or separation of privileges.
+absolute SQLite file, e.g. `file:/tmp/coffre-local.db`; migrate that URL once
+with `pnpm migrate`, and make the keys with `npx @coffre/cli keys`. SQLite
+has no database logins or separation of privileges.
 
 ## 3. Run
 

package/dist/templates/node/package.json

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

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

@@ -4,7 +4,8 @@ PORT=3000
 # Where people reach coffre, through the proxy that terminates TLS in front
 # of it: an origin, no path.
 PUBLIC_URL=https://secrets.example.com
-# The vault uses this Postgres database through a different login.
+# From `coffre setup`: the database, as the server's own login. The vault
+# uses it through another.
 DATABASE_URL=postgres://coffre_runtime:CHANGE_ME@127.0.0.1:5432/coffre
 # The vault's socket, as in vault.env.
 VAULT_SOCKET=vault.sock
@@ -13,6 +14,6 @@ VAULT_SOCKET=vault.sock
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 
-# From `coffre keys`, saved in your password manager first: signs the
-# server's log entries, sessions and tokens.
-AUDIT_CHAIN_KEY=
+# From `coffre setup`, saved in your password manager first: the app key,
+# which signs the server's log entries, sessions and tokens.
+APP_KEY=

package/dist/templates/node/src/server.ts

@@ -1,5 +1,5 @@
 // coffre's server: the API, sign-in, pages and scheduled job, in one
-// process. It holds no KEK: it asks the vault, a process of its own
+// process. It holds no vault key: it asks the vault, a process of its own
 // (src/vault.ts), over a Unix socket. Settings come from server.env.
 import { github, serve, signin } from '@coffre/server/node';
 import { connectVault } from '@coffre/vault/node';
@@ -16,7 +16,7 @@ const server = await serve({
   database: env('DATABASE_URL'),
   vault: connectVault(env('VAULT_SOCKET')),
   // For tests or local SQLite development only, the vault in this process:
-  // vault: await localVault({ database: env('DATABASE_URL'), kek: …, rootAdmins: […], signingKey: … }),
+  // vault: await localVault({ database: env('DATABASE_URL'), kek: …, rootAdmins: […] }),
   auth: signin({
     providers: [
       github({
@@ -28,7 +28,7 @@ const server = await serve({
       }),
     ],
   }),
-  auditChainKey: env('AUDIT_CHAIN_KEY'),
+  auditChainKey: env('APP_KEY'),
 });
 console.log(`coffre is listening on ${server.url}`);
 

package/dist/templates/node/src/vault.ts

@@ -1,7 +1,7 @@
 // The vault: the keys, and the members and grants, which it keeps in the
 // server's database through a login of its own. It answers only on a Unix
 // socket, which it makes 0660: run it as its own user, sharing a group with
-// the server's, and nothing that faces the network can read the KEK.
+// the server's, and nothing that faces the network can read the vault key.
 // Settings come from vault.env.
 import { serveVault } from '@coffre/vault/node';
 
@@ -14,11 +14,13 @@ function env(name: string): string {
 const vault = await serveVault({
   socket: env('VAULT_SOCKET'),
   database: env('DATABASE_URL'),
-  kek: { id: env('KEK_ID'), key: env('KEK') },
-  // After a rotation, the KEKs before it, so the data keys they wrapped
-  // still open: previousKeks: [{ id: 'kek-1', key: env('KEK_1') }],
+  kek: { id: env('VAULT_KEY_ID'), key: env('VAULT_KEY') },
+  // After a rotation, the vault keys before it, so the data keys they wrapped
+  // still open and the records signed under them before it still verify:
+  // previousKeks: [{ id: 'vault-2026-04-01-k7q2xm', key: env('OLD_VAULT_KEY') }],
   rootAdmins: env('ROOT_ADMINS').split(',').map((email) => email.trim()),
-  signingKey: env('SIGNING_KEY'),
+  // The vault derives its signing key from the vault key. With a key a key
+  // service holds, such as awsKms(…), it needs one of its own: signingKey: env('SIGNING_KEY').
 });
 console.log(`the vault is listening on ${vault.socket}`);
 

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

@@ -2,15 +2,15 @@
 # the vault's user alone.
 
 VAULT_SOCKET=vault.sock
-# The server's Postgres database, as the vault's own login.
+# From `coffre setup`: the server's database, as the vault's own login.
 DATABASE_URL=postgres://coffre_vault_runtime:CHANGE_ME@127.0.0.1:5432/coffre
 
-# 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=
-# Signs the vault's log entries, checkpoints and member rows.
-SIGNING_KEY=
+# From `coffre setup`, saved in your password manager first: the vault key,
+# which decrypts every value, and its ID, which is not secret. A rotation
+# gives the new key a new ID. The vault derives the key it signs its
+# records with from it.
+VAULT_KEY_ID=vault-1
+VAULT_KEY=
 
 # Comma-separated emails: the first people in, whom nobody can remove.
 ROOT_ADMINS=you@example.com

package/dist/templates/workers/README.md

@@ -17,76 +17,66 @@ 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`, which `coffre keys` gives you below.
+  and `VAULT_KEY_ID`, which `coffre setup` gives you below.
 
-## 2. The database
+## 2. The database and keys
 
-coffre wants a Postgres database with three logins: its owner, for
-migrations; `coffre_runtime`, which the app runs as; and
-`coffre_vault_runtime`, which the vault runs as. Create the two as plain
-logins. As the database's administrator, connect with `psql` and run:
-
-```sql
-CREATE ROLE coffre_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-CREATE ROLE coffre_vault_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-\password coffre_runtime
-\password coffre_vault_runtime
-```
-
-Each `\password` prompts for a different generated password. The owner
-must be able to create and grant roles: the migration creates `coffre_app`
-and `coffre_vault`, and grants each login its own group. Only the vault may
-write members and grants, and each appends to the log only as itself.
-URL-encode special characters in the passwords in these URLs:
+Make a Postgres database, then, from this directory:
 
 ```sh
-pnpm install
-pnpm migrate "postgres://owner:…@db.example.com:5432/coffre"
-pnpm exec wrangler hyperdrive create coffre --caching-disabled \
-  --connection-string="postgres://coffre_runtime:…@db.example.com:5432/coffre"
-pnpm exec wrangler hyperdrive create coffre-vault --caching-disabled \
-  --connection-string="postgres://coffre_vault_runtime:…@db.example.com:5432/coffre"
+npx @coffre/cli setup
 ```
 
-Keep `--caching-disabled`: Hyperdrive otherwise caches reads for up to a
-minute, and a revoked token or a signed-out session could keep working that
-long. `wrangler.jsonc` cannot set it, so for a config made another way,
-check `caching` in `wrangler hyperdrive get <id>`.
+Run it with the CLI you ran `coffre init` with. It asks for the database
+administrator's connection string at a hidden prompt. A script can pipe it
+in, or set `COFFRE_SETUP_DATABASE_URL`; never pass it as an argument. It
+makes the two logins coffre runs as, `coffre_runtime` for the app and
+`coffre_vault_runtime` for the vault, migrates the database, and checks that
+each login holds only its rights.
+
+Then it shows five values on a screen of their own, which leaves nothing
+behind in your scrollback: the app key and the app's database URL, and the
+vault ID, the vault key and the vault's database URL. Copy each into your
+password manager with `c`, beside the GitHub client secret; `w` shows where
+each one goes. Nothing keeps a copy. There is one key for each Worker, so
+that the app, which faces the network, never holds what decrypts a value:
+
+- `VAULT_KEY`, the vault key, decrypts every value, and the vault derives
+  from it the key it signs its records with. Lose it, and every value is
+  lost.
+- `APP_KEY`, the app key, signs the app's log entries, sessions and tokens.
+  Lose it, and everyone is signed out and the log stops verifying.
+- `VAULT_KEY_ID`, the vault ID, names the vault key. It is not secret.
+
+To do the same by hand, see
+[deploy.md](https://github.com/erwinkn/coffre/blob/main/docs/deploy.md#appendix-the-database-by-hand).
+
+## 3. Hyperdrive and secrets
+
+Run the two `wrangler hyperdrive create` commands from setup's screen: one
+config per login, each `--caching-disabled`. Hyperdrive otherwise caches
+reads for up to a minute, and a revoked token or a signed-out session could
+keep working that long. `wrangler.jsonc` cannot set it, so for a config made
+another way, check `caching` in `wrangler hyperdrive get <id>`.
 
 Put the ids they print under `hyperdrive`, the first in
-`app/wrangler.jsonc` and the second in `vault/wrangler.jsonc`. Run
-`pnpm migrate` again after every upgrade of `@coffre/server`, before
-deploying it.
-
-## 3. Keys
+`app/wrangler.jsonc` and the second in `vault/wrangler.jsonc`, and
+`VAULT_KEY_ID` in `vault/wrangler.jsonc`. Then set the secrets; each command
+prompts for the saved value:
 
 ```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
-pnpm exec wrangler secret put SIGNING_KEY -c vault/wrangler.jsonc
-pnpm exec wrangler secret put AUDIT_CHAIN_KEY -c app/wrangler.jsonc
+pnpm exec wrangler secret put VAULT_KEY -c vault/wrangler.jsonc
+pnpm exec wrangler secret put APP_KEY -c app/wrangler.jsonc
 pnpm exec wrangler secret put GITHUB_CLIENT_SECRET -c app/wrangler.jsonc
 ```
 
-Keep older KEKs after a rotation too: what they wrapped still needs them.
+Run `pnpm migrate`, with the administrator's URL in `DATABASE_URL`, after
+every upgrade of `@coffre/server`, before deploying it.
+
+Keep older vault keys after a rotation, for good: what they wrapped still
+needs them, and so does what the vault signed under them before it. With AWS KMS
+instead of a key of your own, the vault also needs a `SIGNING_KEY`
+([keys](https://github.com/erwinkn/coffre/blob/main/docs/keys.md#aws-kms)).
 
 ## 4. Deploy
 

package/dist/templates/workers/app/src/worker.ts

@@ -12,7 +12,7 @@ type Env = {
   /** Set for GitHub Enterprise Server; github.com otherwise. */
   GITHUB_URL?: string;
   GITHUB_API_URL?: string;
-  AUDIT_CHAIN_KEY: string;
+  APP_KEY: string;
 };
 
 export default coffre((env: Env) => ({
@@ -29,5 +29,5 @@ export default coffre((env: Env) => ({
       }),
     ],
   }),
-  auditChainKey: env.AUDIT_CHAIN_KEY,
+  auditChainKey: env.APP_KEY,
 }));

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

@@ -17,11 +17,11 @@
     "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"]
+    // APP_KEY is from `coffre setup`; the app never gets the vault's keys.
+    "required": ["GITHUB_CLIENT_SECRET", "APP_KEY"]
   },
-  // `wrangler hyperdrive create coffre --caching-disabled --connection-string=<runtime login URL>`
-  // prints the id. Caching must stay off, or a revoked session keeps working
+  // `wrangler hyperdrive create coffre --caching-disabled`, as `coffre setup`
+  // shows it, prints the id. Caching must stay off, or a revoked session keeps working
   // for about a minute, and this file cannot set it: see README.md. Locally,
   // CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE stands in for
   // the config.

package/dist/templates/workers/package.json

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

package/dist/templates/workers/vault/src/worker.ts

@@ -5,17 +5,18 @@ import { postgres, vault } from '@coffre/vault/cloudflare';
 
 type Env = {
   VAULT_HYPERDRIVE: Hyperdrive;
-  KEK_ID: string;
-  KEK: string;
-  SIGNING_KEY: string;
+  VAULT_KEY_ID: string;
+  VAULT_KEY: string;
   ROOT_ADMINS: string;
 };
 
 export default vault((env: Env) => ({
   database: postgres(env.VAULT_HYPERDRIVE),
-  kek: { id: env.KEK_ID, key: env.KEK },
-  // After a rotation, the KEKs before it, so the data keys they wrapped
-  // still open: previousKeks: [{ id: 'kek-2026-09', key: env.KEK_2026_09 }],
+  kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY },
+  // After a rotation, the vault keys before it, so the data keys they wrapped
+  // still open and the records signed under them before it still verify:
+  // previousKeks: [{ id: 'vault-2026-04-01-k7q2xm', key: env.OLD_VAULT_KEY }],
   rootAdmins: env.ROOT_ADMINS.split(',').map((email) => email.trim()),
-  signingKey: env.SIGNING_KEY,
+  // The vault derives its signing key from the vault key. With a key a key
+  // service holds, such as awsKms(…), it needs one of its own: signingKey: env.SIGNING_KEY.
 }));

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

@@ -11,18 +11,20 @@
   "workers_dev": false,
   "observability": { "enabled": true },
   "vars": {
-    // Names the KEK below: from `coffre keys`. A rotation gives the new one a new id.
-    "KEK_ID": "kek-1",
+    // Names the vault key below, and is not secret: from `coffre setup`. A
+    // rotation gives the new key a new ID.
+    "VAULT_KEY_ID": "vault-1",
     // Comma-separated emails: the first people in, whom nobody can remove.
     "ROOT_ADMINS": "you@example.com"
   },
   "secrets": {
-    // From `coffre keys`: wrangler secret put KEK, then SIGNING_KEY.
-    "required": ["KEK", "SIGNING_KEY"]
+    // The vault key, from `coffre setup`: wrangler secret put VAULT_KEY. The
+    // vault derives the key it signs its records with from it.
+    "required": ["VAULT_KEY"]
   },
   // The app's database, as the vault's own login: `wrangler hyperdrive
-  // create coffre-vault --caching-disabled --connection-string=<vault login
-  // URL>` prints the id. Its own config, not the app's: the vault writes
+  // create coffre-vault --caching-disabled`, as `coffre setup` shows it,
+  // prints the id. Its own config, not the app's: the vault writes
   // members and grants, which the app's login may only read. Locally,
   // CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_VAULT_HYPERDRIVE stands in.
   "hyperdrive": [{ "binding": "VAULT_HYPERDRIVE", "id": "replace-with-your-vault-hyperdrive-id" }]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The coffre command line: secrets in your shell, and `coffre init` for a new deployment.",
   "license": "MIT",
   "repository": {
@@ -23,13 +23,16 @@
   },
   "devDependencies": {
     "@types/node": "26.1.1",
+    "@types/pg": "8.20.0",
+    "pg": "8.16.3",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/core": "0.1.1",
-    "@coffre/client": "0.1.1"
+    "@coffre/client": "0.1.3",
+    "@coffre/core": "0.1.3",
+    "@coffre/db": "0.1.3"
   },
   "scripts": {
-    "build": "tsdown && node scripts/copy-templates.ts",
+    "build": "tsdown && node scripts/copy-templates.ts && node scripts/copy-migrations.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --conditions=coffre:source --test"
   }