@coffre/vault 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erwin Kuhn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @coffre/vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+coffre's vault: the keys and who holds what. It decides every read and
+write of a key and appends to the shared audit log as `vault`. It runs as a
+Worker beside the app's Worker, or as its own process on Node. Both use
+one Postgres database, each through its own restricted login:
+
+```ts
+import { postgres, vault } from '@coffre/vault/cloudflare';
+
+export default vault((env) => ({
+  database: postgres(env.VAULT_HYPERDRIVE), // coffre_vault_runtime, caching disabled
+  kek: { id: env.KEK_ID, key: env.KEK }, // or awsKms({ keyArn, credentials })
+  rootAdmins: env.ROOT_ADMINS.split(','),
+  signingKey: env.SIGNING_KEY,
+}));
+```
+
+On Node, `serveVault({ socket, database, … })` from `@coffre/vault/node`,
+with the vault's Postgres URL. Only `coffre_vault_runtime` may write members
+and grants; the app uses `coffre_runtime`. See the
+[deploy guide](https://github.com/erwinkn/coffre/blob/main/docs/deploy.md)
+for the logins and both Hyperdrive configs.
+
+Part of [coffre](https://github.com/erwinkn/coffre), a secrets manager you
+deploy as a small project of your own. Its eight `@coffre/*` packages are
+released together, at one version. MIT licensed.

package/dist/cloudflare.d.ts

@@ -0,0 +1,55 @@
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+import { AdmitInput, RemoveInput, RewrapInput, SetAccessInput, UnwrapInput, Vault, VerifyLogInput, WrapInput } from "@coffre/core/vault";
+import { PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
+import { WorkerEntrypoint } from "cloudflare:workers";
+export * from "@coffre/core/vault";
+//#region src/cloudflare.d.ts
+/** What the vault Worker's `vault(env => …)` returns. */
+export type WorkersVaultConfig = VaultConfig & {
+  database: PostgresDatabase$1;
+};
+/**
+ * What the app's `VAULT` service binding calls. Each call gets a database of
+ * its own, since a Worker's connections belong to the call that made them.
+ */
+export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
+  #private;
+  unwrap(input: UnwrapInput): Promise<import("@coffre/core/vault").Outcome<{
+    keys: string[];
+  }>>;
+  wrap(input: WrapInput): Promise<import("@coffre/core/vault").Outcome<{
+    wrapped: import("@coffre/core/vault").WrappedKey[];
+    seqs: number[];
+  }>>;
+  rewrap(input: RewrapInput): Promise<import("@coffre/core/vault").Outcome<{
+    wrapped: import("@coffre/core/vault").WrappedKey[];
+    seqs: number[];
+  }>>;
+  access(principal: string): Promise<import("@coffre/core/vault").Access>;
+  setAccess(input: SetAccessInput): Promise<import("@coffre/core/vault").Outcome<{
+    changes: import("@coffre/core/vault").AccessChange[];
+  }>>;
+  admit(input: AdmitInput): Promise<import("@coffre/core/vault").Outcome<{
+    created: boolean;
+    owner: boolean;
+    generation: number;
+  }>>;
+  remove(input: RemoveInput): Promise<import("@coffre/core/vault").Outcome<{
+    revoked: import("@coffre/core/vault").Grant[];
+    generation: number;
+  }>>;
+  checkpoint(): Promise<import("@coffre/core/vault").Outcome<{
+    checkpoint: import("@coffre/core/vault").Checkpoint;
+  }>>;
+  about(): Promise<{
+    publicKey: string;
+    rootAdmins: string[];
+  }>;
+  verifyLog(input: VerifyLogInput): Promise<import("@coffre/core/vault").LogVerification>;
+  /** No HTTP surface: only the app's service binding reaches the vault. */
+  fetch(): Response;
+}
+/** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
+export declare function vault<Env>(configure_: (env: Env) => WorkersVaultConfig): typeof VaultEntrypoint;
+//#endregion
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, postgres, verifyCheckpoint };

package/dist/cloudflare.js

@@ -0,0 +1,73 @@
+import { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint } from "./index.js";
+import { n as prepareVault, r as resolveVaultConfig, t as openVault } from "./vault-DvTsSAOX.js";
+import { createDatabase } from "@coffre/db";
+import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
+import { WorkerEntrypoint } from "cloudflare:workers";
+//#region src/cloudflare.ts
+/** Set when the Worker's module runs `vault(…)`, before any call comes in. */
+let configure = null;
+/** The configuration, checked and made ready once per `env`, which the isolate keeps. */
+const ready = /* @__PURE__ */ new WeakMap();
+/**
+* What the app's `VAULT` service binding calls. Each call gets a database of
+* its own, since a Worker's connections belong to the call that made them.
+*/
+var VaultEntrypoint = class extends WorkerEntrypoint {
+	async #vault() {
+		const env = this.env;
+		let entry = ready.get(env);
+		if (entry === void 0) {
+			if (configure === null) throw new Error("the vault Worker must export default vault(…)");
+			const config = configure(env);
+			entry = prepareVault(resolveVaultConfig(config)).then((prepared) => ({
+				database: config.database,
+				prepared
+			}));
+			ready.set(env, entry);
+			entry.catch(() => ready.delete(env));
+		}
+		const { database, prepared } = await entry;
+		return openVault(createDatabase(new HyperdrivePool(database.hyperdrive.connectionString)), prepared);
+	}
+	async unwrap(input) {
+		return (await this.#vault()).unwrap(input);
+	}
+	async wrap(input) {
+		return (await this.#vault()).wrap(input);
+	}
+	async rewrap(input) {
+		return (await this.#vault()).rewrap(input);
+	}
+	async access(principal) {
+		return (await this.#vault()).access(principal);
+	}
+	async setAccess(input) {
+		return (await this.#vault()).setAccess(input);
+	}
+	async admit(input) {
+		return (await this.#vault()).admit(input);
+	}
+	async remove(input) {
+		return (await this.#vault()).remove(input);
+	}
+	async checkpoint() {
+		return (await this.#vault()).checkpoint();
+	}
+	async about() {
+		return (await this.#vault()).about();
+	}
+	async verifyLog(input) {
+		return (await this.#vault()).verifyLog(input);
+	}
+	/** No HTTP surface: only the app's service binding reaches the vault. */
+	fetch() {
+		return new Response("not found", { status: 404 });
+	}
+};
+/** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
+function vault(configure_) {
+	configure = configure_;
+	return VaultEntrypoint;
+}
+//#endregion
+export { KekBadClaimError, KekUnavailableError, VaultEntrypoint, awsKms, checkpointMessage, postgres, vault, verifyCheckpoint };

package/dist/index-qXbB_vlp.d.ts

@@ -0,0 +1,40 @@
+import { checkpointMessage as checkpointMessage$1, verifyCheckpoint as verifyCheckpoint$1 } from "@coffre/core/vault";
+import { AwsCredentials, AwsKmsOptions, KekBadClaimError as KekBadClaimError$1, KekProvider, KekProvider as KekProvider$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, WrappedDek, awsKms } from "@coffre/core/kek";
+import { SecretContext } from "@coffre/core/envelope";
+//#region src/config.d.ts
+/**
+ * A key-encryption key: 32 random bytes, base64, and the id envelopes record
+ * it under; or one a key service holds, such as `awsKms({ keyArn, … })`.
+ */
+type Kek = {
+  id: string;
+  key: string;
+} | KekProvider;
+/**
+ * What a deployment writes: every key coffre has, and who may always get
+ * in. The app holds none of it.
+ *
+ *   {
+ *     kek: awsKms({ keyArn: env.KMS_KEY_ARN, credentials: { … } }),
+ *     previousKeks: [{ id: 'kek-2025-01', key: env.KEK_2025_01 }],
+ *     rootAdmins: ['admin@acme.example'],
+ *     signingKey: env.SIGNING_KEY,
+ *   }
+ */
+type VaultConfig = {
+  /** Wraps every new data key. */
+  kek: Kek;
+  /** Older KEKs, still unwrapping what they wrapped until a rewrap moves it on. */
+  previousKeks?: readonly Kek[];
+  /** At least one email: the only way into a fresh instance, and the only members nobody can remove. */
+  rootAdmins: readonly string[];
+  /** 32 random bytes, base64: the Ed25519 seed audit checkpoints are signed with. */
+  signingKey: string;
+  /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
+  bulkLimit?: {
+    count: number;
+    windowMinutes: number;
+  };
+};
+//#endregion
+export { KekUnavailableError$1 as a, awsKms as c, Kek as d, VaultConfig as f, KekProvider$1 as i, checkpointMessage$1 as l, AwsKmsOptions as n, SecretContext as o, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint$1 as u };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+export type * from "@coffre/core/vault";
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, verifyCheckpoint };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { checkpointMessage, verifyCheckpoint } from "@coffre/core/vault";
+import { KekBadClaimError, KekUnavailableError, awsKms } from "@coffre/core/kek";
+export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint };

package/dist/node.d.ts

@@ -0,0 +1,48 @@
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-qXbB_vlp.js";
+import { Vault, Vault as Vault$1 } from "@coffre/core/vault";
+import { Database } from "@coffre/db";
+import "@coffre/core/audit";
+export * from "@coffre/core/vault";
+//#region src/vault.d.ts
+type VaultOptions = {
+  /**
+   * How long every key operation of one call may take, in milliseconds;
+   * 5 seconds unless set. Past it, a call fails as an outage.
+   */
+  keyBudgetMs?: number;
+  /** Milliseconds added to the database's clock where the vault decides by it. Tests move time with it. */
+  clockOffset?: () => number;
+};
+//#endregion
+//#region src/local.d.ts
+type LocalVault = Vault$1 & {
+  close(): Promise<void>;
+};
+//#endregion
+//#region src/node.d.ts
+export type NodeVaultConfig = VaultConfig & {
+  /**
+   * The database the server uses, as the vault's own login:
+   * `postgres://coffre_vault_runtime:…@…/coffre`, or a `file:` URL for local
+   * development. Or one already open, which the vault leaves open.
+   */
+  database: string | Database;
+};
+/** The vault in this process. */
+export declare function localVault(config: NodeVaultConfig, options?: VaultOptions): Promise<LocalVault>;
+export type VaultServer = {
+  socket: string;
+  close(): Promise<void>;
+};
+/**
+ * The vault as a process of its own, answering on a Unix socket. The socket
+ * is made `0660`: put it in a directory the server's user can reach through
+ * a shared group, e.g. `/run/coffre/vault.sock`.
+ */
+export declare function serveVault(config: NodeVaultConfig & {
+  socket: string;
+}): Promise<VaultServer>;
+/** The vault that `serveVault` runs, from the server's side of its socket. */
+export declare function connectVault(socket: string): Vault;
+//#endregion
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type LocalVault, type SecretContext, type Vault, type VaultConfig, type VaultOptions, type WrappedDek, awsKms, checkpointMessage, verifyCheckpoint };

package/dist/node.js

@@ -0,0 +1,142 @@
+import { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, verifyCheckpoint } from "./index.js";
+import { n as prepareVault, r as resolveVaultConfig, t as openVault } from "./vault-DvTsSAOX.js";
+import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
+import { Agent, createServer, request } from "node:http";
+import { openDatabase } from "@coffre/db/connect";
+//#region src/local.ts
+/** Every call the vault answers, in the order of the `Vault` interface. */
+const METHODS = [
+	"unwrap",
+	"wrap",
+	"rewrap",
+	"access",
+	"setAccess",
+	"admit",
+	"remove",
+	"checkpoint",
+	"about",
+	"verifyLog"
+];
+/**
+* The vault in this process, over `db`. Every argument and result goes
+* through JSON on the way, as it would over RPC or a socket, so what works
+* here does not rely on sharing objects with the caller. `close` is
+* whatever lets go of the database, when the vault opened it.
+*/
+async function openLocalVault(db, config, options = {}, close = async () => {}) {
+	const vault = openVault(db, await prepareVault(config, options));
+	const local = Object.fromEntries(METHODS.map((name) => [name, async (...args) => json(await vault[name](...json(args)))]));
+	return Object.assign(local, { close });
+}
+function json(value) {
+	return value === void 0 ? void 0 : JSON.parse(JSON.stringify(value));
+}
+//#endregion
+//#region src/node.ts
+/**
+* The vault on Node, one of two ways, each over the database the server
+* uses, through the vault's own login:
+*
+* - in the server's own process: `vault: await localVault({ database, ...keys })`;
+* - as a process of its own, which the server reaches over a Unix socket:
+*   `serveVault({ socket, database, ...keys })` there, and
+*   `vault: connectVault(socket)` in the server.
+*
+* The second keeps every key out of the process that faces the network. The
+* socket is the whole of its authentication: a file only the vault's user
+* and the group it shares with the server may open, so no port to reach and
+* no shared secret to leak. Each call is one HTTP POST over it, `/<method>`
+* with the arguments as a JSON array, and refusals come back as values, as
+* from any vault; only a failure is an error.
+*/
+/** The vault in this process. */
+async function localVault(config, options = {}) {
+	const resolved = resolveVaultConfig(config);
+	if (typeof config.database !== "string") return openLocalVault(config.database, resolved, options);
+	const { db, close } = await openDatabase(config.database);
+	return openLocalVault(db, resolved, options, close).catch(async (error) => {
+		await close();
+		throw error;
+	});
+}
+const METHOD_NAMES = new Set(METHODS);
+const MAX_BODY = 8388608;
+/**
+* The vault as a process of its own, answering on a Unix socket. The socket
+* is made `0660`: put it in a directory the server's user can reach through
+* a shared group, e.g. `/run/coffre/vault.sock`.
+*/
+async function serveVault(config) {
+	const vault = await localVault(config);
+	const server = createServer(async (req, res) => {
+		const name = (req.url ?? "").slice(1);
+		const reply = (status, body) => {
+			res.writeHead(status, { "content-type": "application/json" });
+			res.end(JSON.stringify(body));
+		};
+		if (req.method !== "POST" || !METHOD_NAMES.has(name)) return reply(404, { error: "not a vault call" });
+		try {
+			const args = JSON.parse(await readBody(req));
+			if (!Array.isArray(args)) return reply(400, { error: "the arguments must be a JSON array" });
+			const result = await vault[name](...args);
+			reply(200, result === void 0 ? {} : { result });
+		} catch (error) {
+			console.error(`vault ${name} failed`, error);
+			reply(500, { error: error instanceof Error ? error.message : "the vault failed" });
+		}
+	});
+	if (existsSync(config.socket)) {
+		if (!lstatSync(config.socket).isSocket()) throw new Error(`${config.socket} exists and is not a socket`);
+		rmSync(config.socket);
+	}
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(config.socket, () => resolve());
+	});
+	chmodSync(config.socket, 432);
+	return {
+		socket: config.socket,
+		close: () => new Promise((resolve) => {
+			server.close(() => void vault.close().then(resolve));
+			server.closeAllConnections();
+		})
+	};
+}
+/** The vault that `serveVault` runs, from the server's side of its socket. */
+function connectVault(socket) {
+	const agent = new Agent({ keepAlive: true });
+	const call = (name) => (...args) => new Promise((resolve, reject) => {
+		const body = JSON.stringify(args);
+		const req = request({
+			socketPath: socket,
+			agent,
+			method: "POST",
+			path: `/${name}`,
+			headers: {
+				"content-type": "application/json",
+				"content-length": Buffer.byteLength(body)
+			}
+		}, (res) => {
+			readBody(res).then((text) => {
+				const payload = JSON.parse(text);
+				if (res.statusCode === 200) resolve(payload.result);
+				else reject(/* @__PURE__ */ new Error(`vault ${name}: ${payload.error ?? `status ${res.statusCode}`}`));
+			}, reject);
+		});
+		req.on("error", (error) => reject(/* @__PURE__ */ new Error(`the vault at ${socket} is unreachable: ${error.message}`)));
+		req.end(body);
+	});
+	return Object.fromEntries(METHODS.map((name) => [name, call(name)]));
+}
+async function readBody(stream) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of stream) {
+		size += chunk.length;
+		if (size > MAX_BODY) throw new Error("the message is too large");
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+//#endregion
+export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, connectVault, localVault, serveVault, verifyCheckpoint };