@coffre/core 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,12 @@
-# Temporary Holding Version
+# @coffre/core
 
-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.
+What coffre's other packages share: access rules, envelope encryption, the
+key-encryption keys (a local key, or AWS KMS), the audit chain, identity and
+sign-in, and `Vault`, the contract between the server and the vault.
+
+A deployment does not import it. `@coffre/server` and `@coffre/vault`
+re-export what a deployment needs from it.
+
+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/access.d.ts

@@ -0,0 +1,100 @@
+//#region src/access.d.ts
+/**
+ * Who may do what: seven permissions and the six roles that bundle them.
+ *
+ * Deliberately constants and not tables or a policy language. A grant names
+ * one role for one member on one place, and a check is a lookup in this file,
+ * so authorisation stays something you can read end to end.
+ */
+export declare const PERMISSIONS: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
+export type Permission = (typeof PERMISSIONS)[number];
+/**
+ * Permissions that only make sense on a project. Granting
+ * `environment.manage` on one environment would be incoherent: what it
+ * authorises is creating that environment's siblings.
+ */
+export declare const PROJECT_ONLY_PERMISSIONS: readonly Permission[];
+export declare const ROLES: {
+  readonly viewer: {
+    readonly name: "Viewer";
+    readonly description: "Read secret values.";
+    readonly permissions: readonly ["secret.read"];
+  };
+  readonly developer: {
+    readonly name: "Developer";
+    readonly description: "Read and write secrets.";
+    readonly permissions: readonly ["secret.read", "secret.write"];
+  };
+  readonly maintainer: {
+    readonly name: "Maintainer";
+    readonly description: "Read, write and retire secrets, and manage environments.";
+    readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "environment.manage"];
+  };
+  readonly 'access-manager': {
+    readonly name: "Access manager";
+    readonly description: "Manage who has access. Cannot read secret values.";
+    readonly permissions: readonly ["grant.manage"];
+  };
+  readonly auditor: {
+    readonly name: "Auditor";
+    readonly description: "Read the audit log. Cannot read secret values.";
+    readonly permissions: readonly ["audit.read"];
+  };
+  readonly owner: {
+    readonly name: "Owner";
+    readonly description: "Everything, including reading secret values.";
+    readonly permissions: readonly ["secret.read", "secret.write", "secret.archive", "audit.read", "environment.manage", "grant.manage", "project.manage"];
+  };
+};
+export type Role = keyof typeof ROLES;
+export declare const ROLE_NAMES: Role[];
+export declare function isRole(value: string): value is Role;
+export declare function roleGrants(role: Role, permission: Permission): boolean;
+/** Roles that hold a project-only permission can only be granted on a project. */
+export declare function assignableToEnvironment(role: Role): boolean;
+/** A place a permission applies to: a project, or one of its environments. */
+export type Place = {
+  projectId: string;
+  environmentId?: string | null;
+};
+/**
+ * What someone holds: everything a permission check reads. The app builds
+ * it from what the vault says once per request; the vault builds it from
+ * its own store. Both then ask the same functions below, so the rules
+ * cannot drift apart.
+ */
+export type Holdings = {
+  /** Named in the vault's configuration: everything, everywhere. */
+  isRootAdmin: boolean;
+  /** Root admins and active users with the instance `owner` role. */
+  isOwner: boolean;
+  /** Live grants only. */
+  grants: readonly {
+    projectId: string;
+    environmentId: string | null;
+    role: Role;
+  }[];
+};
+/**
+ * Whether `holder` may do `permission` at `place`.
+ *
+ *   on a project       its project grant; owners also manage every project
+ *   on an environment  its environment grant or its project's grant
+ *
+ * An environment grant never reaches up to the project: `developer` on
+ * `market/prod` does not let anyone rename `market`.
+ */
+export declare function allows(holder: Holdings, permission: Permission, place: Place): boolean;
+/** A sync reads as a principal of its own, `sync:<id>`. */
+export declare function isSyncPrincipal(principal: string): boolean;
+/**
+ * Whether `actor` may set `subject`'s role at `place`, or take it away
+ * (`role` null). `grant.manage` on the project decides, with one addition:
+ * whoever may manage a project's environments may let a sync read an
+ * environment they can read themselves, and take that away again, since
+ * adding and removing syncs is theirs to do.
+ */
+export declare function mayManageAccess(actor: Holdings, subject: string, change: Place & {
+  role: Role | null;
+}): boolean;
+//#endregion

package/dist/access.js

@@ -0,0 +1,109 @@
+//#region src/access.ts
+/**
+* Who may do what: seven permissions and the six roles that bundle them.
+*
+* Deliberately constants and not tables or a policy language. A grant names
+* one role for one member on one place, and a check is a lookup in this file,
+* so authorisation stays something you can read end to end.
+*/
+const PERMISSIONS = [
+	"secret.read",
+	"secret.write",
+	"secret.archive",
+	"audit.read",
+	"environment.manage",
+	"grant.manage",
+	"project.manage"
+];
+/**
+* Permissions that only make sense on a project. Granting
+* `environment.manage` on one environment would be incoherent: what it
+* authorises is creating that environment's siblings.
+*/
+const PROJECT_ONLY_PERMISSIONS = [
+	"environment.manage",
+	"grant.manage",
+	"project.manage"
+];
+const ROLES = {
+	viewer: {
+		name: "Viewer",
+		description: "Read secret values.",
+		permissions: ["secret.read"]
+	},
+	developer: {
+		name: "Developer",
+		description: "Read and write secrets.",
+		permissions: ["secret.read", "secret.write"]
+	},
+	maintainer: {
+		name: "Maintainer",
+		description: "Read, write and retire secrets, and manage environments.",
+		permissions: [
+			"secret.read",
+			"secret.write",
+			"secret.archive",
+			"environment.manage"
+		]
+	},
+	"access-manager": {
+		name: "Access manager",
+		description: "Manage who has access. Cannot read secret values.",
+		permissions: ["grant.manage"]
+	},
+	auditor: {
+		name: "Auditor",
+		description: "Read the audit log. Cannot read secret values.",
+		permissions: ["audit.read"]
+	},
+	owner: {
+		name: "Owner",
+		description: "Everything, including reading secret values.",
+		permissions: [...PERMISSIONS]
+	}
+};
+const ROLE_NAMES = Object.keys(ROLES);
+function isRole(value) {
+	return Object.hasOwn(ROLES, value);
+}
+function roleGrants(role, permission) {
+	return ROLES[role].permissions.includes(permission);
+}
+/** Roles that hold a project-only permission can only be granted on a project. */
+function assignableToEnvironment(role) {
+	return !ROLES[role].permissions.some((permission) => PROJECT_ONLY_PERMISSIONS.includes(permission));
+}
+/**
+* Whether `holder` may do `permission` at `place`.
+*
+*   on a project       its project grant; owners also manage every project
+*   on an environment  its environment grant or its project's grant
+*
+* An environment grant never reaches up to the project: `developer` on
+* `market/prod` does not let anyone rename `market`.
+*/
+function allows(holder, permission, place) {
+	if (holder.isRootAdmin) return true;
+	const environmentId = place.environmentId ?? null;
+	if (environmentId === null && holder.isOwner && PROJECT_ONLY_PERMISSIONS.includes(permission)) return true;
+	return holder.grants.some((grant) => grant.projectId === place.projectId && (grant.environmentId === null || grant.environmentId === environmentId) && roleGrants(grant.role, permission));
+}
+/** A sync reads as a principal of its own, `sync:<id>`. */
+function isSyncPrincipal(principal) {
+	return principal.startsWith("sync:");
+}
+/**
+* Whether `actor` may set `subject`'s role at `place`, or take it away
+* (`role` null). `grant.manage` on the project decides, with one addition:
+* whoever may manage a project's environments may let a sync read an
+* environment they can read themselves, and take that away again, since
+* adding and removing syncs is theirs to do.
+*/
+function mayManageAccess(actor, subject, change) {
+	if (allows(actor, "grant.manage", { projectId: change.projectId })) return true;
+	if (!isSyncPrincipal(subject) || !allows(actor, "environment.manage", { projectId: change.projectId })) return false;
+	if (change.role === null) return true;
+	return change.role === "viewer" && (change.environmentId ?? null) !== null && allows(actor, "secret.read", change);
+}
+//#endregion
+export { PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_NAMES, allows, assignableToEnvironment, isRole, isSyncPrincipal, mayManageAccess, roleGrants };

package/dist/audit.d.ts

@@ -0,0 +1,119 @@
+//#region src/audit/chain.d.ts
+/**
+ * The audit log's format: one chain, written by two authors, the app and the
+ * vault (docs/design/single-database.md, question 6).
+ *
+ *   mac  = HMAC-SHA256(author's key, "coffre.audit.mac.v2"   ‖ prev_hash ‖ fields)
+ *   hash = SHA-256(                  "coffre.audit.chain.v2" ‖ prev_hash ‖ fields ‖ mac)
+ *
+ * The MAC says which author wrote an entry: only the holder of its key can
+ * make it. The hash is public: anyone who can read the table can check that
+ * each entry follows the one before, MACs included, so a signed checkpoint
+ * pins a prefix byte for byte. Because each MAC covers the previous hash, an
+ * author can rewrite only its own entries since the other's last one.
+ *
+ * This authenticates what is retained, not its freshness: rolling back the
+ * log and its head together needs no key. That limit is accepted (question 7).
+ *
+ * Both authors encode through this module, and test/vectors/audit-v2.json
+ * pins the bytes, so they cannot drift apart. A change to what is encoded is
+ * a new format version, never an edit of this one.
+ */
+/** Part of the format: a change to the encoding changes these. */
+export declare const LOG_FORMAT = "coffre.audit.v2";
+/** Length of a chain hash, and of a MAC, in bytes. */
+export declare const HASH_BYTES = 32;
+/** The `prev_hash` of the first entry. */
+export declare const GENESIS_HASH: Buffer;
+export type Author = 'app' | 'vault';
+/**
+ * Every field an entry's MAC and hash cover, in their order. Times are
+ * milliseconds since the epoch, from the database's clock; sequence numbers
+ * are bigints, encoded in decimal; `metadata` is JSON text, covered as
+ * stored.
+ */
+export type LogFields = {
+  seq: bigint;
+  author: Author;
+  keyId: string;
+  occurredAt: number;
+  actor: string;
+  action: string;
+  decision: string;
+  code: string | null;
+  subjectPrincipal: string | null;
+  projectId: string | null;
+  environmentId: string | null;
+  secretId: string | null;
+  secretVersionId: string | null;
+  operationId: string | null;
+  requestId: string | null;
+  sourceIp: string | null;
+  relatedSeq: bigint | null;
+  metadata: string;
+};
+/**
+ * The fields as bytes, injectively: each is length-prefixed, a null is
+ * length -1, distinct from the empty string, and numbers are decimal text.
+ * Strings contain Unicode scalar values: lone UTF-16 surrogates are refused,
+ * not replaced on conversion to UTF-8. Undefined is not a wire value.
+ */
+export declare function encodeFields(fields: LogFields): Buffer;
+/** A key one author MACs its entries with, and the id each entry records. */
+export type LogKey = {
+  author: Author;
+  keyId: string;
+  key: Buffer;
+};
+/**
+ * An author's log key, derived from one of its secrets: `auditChainKey` for
+ * the app. The id is a fingerprint of the key, so a rotation shows in every
+ * entry, and an old key can be kept for verification by its id.
+ */
+export declare function deriveLogKey(author: Author, secret: Uint8Array): LogKey;
+/** The MAC of an entry, under its author's key. */
+export declare function entryMac(key: Buffer, prevHash: Buffer, fields: LogFields): Buffer;
+/** The public hash of an entry, which the next one chains to. */
+export declare function entryHash(prevHash: Buffer, fields: LogFields, mac: Buffer): Buffer;
+/** An entry's MAC and hash, as `key` writes it after `prevHash`. */
+export declare function sealEntry(key: LogKey, prevHash: Buffer, fields: LogFields): {
+  mac: Buffer;
+  hash: Buffer;
+};
+export type StoredEntry = LogFields & {
+  prevHash: Buffer;
+  mac: Buffer;
+  hash: Buffer;
+};
+export type ChainVerification =
+/** `authenticated` is below `entries` only for a `chainOnly` author's entries. */
+{
+  ok: true;
+  entries: number;
+  head: Buffer;
+  nextSeq: bigint;
+  authenticated: number;
+} | {
+  ok: false;
+  failedAtSeq: bigint;
+  reason: string;
+};
+/**
+ * Check a run of entries, oldest first: that the numbers run on from
+ * `startSeq` without a gap, that each links to the hash before it, that each
+ * hash is its entry's, and that each entry carries a MAC from one of `keys`.
+ *
+ * An author whose key the verifier does not hold fails every entry it wrote,
+ * unless it is named in `chainOnly`: then its entries are checked for their
+ * place in the chain only, and `authenticated` counts the rest. That is a
+ * partial verdict, for a caller that has the other author check its own
+ * entries over the same prefix; the public chain alone proves nothing about
+ * who wrote an entry, since anyone who can insert a row can link it.
+ */
+export declare function verifyEntries(entries: readonly StoredEntry[], { startSeq, startPrevHash, keys, chainOnly }: {
+  startSeq?: bigint;
+  startPrevHash?: Buffer;
+  keys: readonly LogKey[];
+  chainOnly?: readonly Author[];
+}): ChainVerification;
+//#endregion

package/dist/audit.js

@@ -0,0 +1,160 @@
+import { createHash, createHmac, hkdfSync, timingSafeEqual } from "node:crypto";
+//#region src/audit/chain.ts
+/**
+* The audit log's format: one chain, written by two authors, the app and the
+* vault (docs/design/single-database.md, question 6).
+*
+*   mac  = HMAC-SHA256(author's key, "coffre.audit.mac.v2"   ‖ prev_hash ‖ fields)
+*   hash = SHA-256(                  "coffre.audit.chain.v2" ‖ prev_hash ‖ fields ‖ mac)
+*
+* The MAC says which author wrote an entry: only the holder of its key can
+* make it. The hash is public: anyone who can read the table can check that
+* each entry follows the one before, MACs included, so a signed checkpoint
+* pins a prefix byte for byte. Because each MAC covers the previous hash, an
+* author can rewrite only its own entries since the other's last one.
+*
+* This authenticates what is retained, not its freshness: rolling back the
+* log and its head together needs no key. That limit is accepted (question 7).
+*
+* Both authors encode through this module, and test/vectors/audit-v2.json
+* pins the bytes, so they cannot drift apart. A change to what is encoded is
+* a new format version, never an edit of this one.
+*/
+/** Part of the format: a change to the encoding changes these. */
+const LOG_FORMAT = "coffre.audit.v2";
+const MAC_DOMAIN = Buffer.from("coffre.audit.mac.v2", "utf8");
+const CHAIN_DOMAIN = Buffer.from("coffre.audit.chain.v2", "utf8");
+/** Length of a chain hash, and of a MAC, in bytes. */
+const HASH_BYTES = 32;
+/** The `prev_hash` of the first entry. */
+const GENESIS_HASH = Buffer.alloc(32, 0);
+const FIELD_ORDER = [
+	"seq",
+	"author",
+	"keyId",
+	"occurredAt",
+	"actor",
+	"action",
+	"decision",
+	"code",
+	"subjectPrincipal",
+	"projectId",
+	"environmentId",
+	"secretId",
+	"secretVersionId",
+	"operationId",
+	"requestId",
+	"sourceIp",
+	"relatedSeq",
+	"metadata"
+];
+/**
+* The fields as bytes, injectively: each is length-prefixed, a null is
+* length -1, distinct from the empty string, and numbers are decimal text.
+* Strings contain Unicode scalar values: lone UTF-16 surrogates are refused,
+* not replaced on conversion to UTF-8. Undefined is not a wire value.
+*/
+function encodeFields(fields) {
+	const parts = [];
+	for (const name of FIELD_ORDER) {
+		const raw = fields[name];
+		const header = Buffer.alloc(4);
+		if (raw === void 0) throw new Error(`${name} cannot be undefined`);
+		if (raw === null) {
+			header.writeInt32BE(-1, 0);
+			parts.push(header);
+			continue;
+		}
+		if (typeof raw === "number" && !Number.isSafeInteger(raw)) throw new Error(`${name} must be a whole number`);
+		if (typeof raw === "string" && /[\uD800-\uDFFF]/u.test(raw)) throw new Error(`${name} must be well-formed Unicode`);
+		const value = Buffer.from(typeof raw === "string" ? raw : raw.toString(10), "utf8");
+		header.writeInt32BE(value.length, 0);
+		parts.push(header, value);
+	}
+	return Buffer.concat(parts);
+}
+/**
+* An author's log key, derived from one of its secrets: `auditChainKey` for
+* the app. The id is a fingerprint of the key, so a rotation shows in every
+* entry, and an old key can be kept for verification by its id.
+*/
+function deriveLogKey(author, secret) {
+	if (secret.length < 32) throw new Error("a log key needs at least 32 bytes of secret");
+	const key = Buffer.from(hkdfSync("sha256", secret, /* @__PURE__ */ new Uint8Array(0), `coffre.audit.${author}.v2`, 32));
+	return {
+		author,
+		keyId: `${author}:${createHash("sha256").update(key).digest("hex").slice(0, 16)}`,
+		key
+	};
+}
+/** The MAC of an entry, under its author's key. */
+function entryMac(key, prevHash, fields) {
+	checkHash(prevHash, "prevHash");
+	return createHmac("sha256", key).update(MAC_DOMAIN).update(prevHash).update(encodeFields(fields)).digest();
+}
+/** The public hash of an entry, which the next one chains to. */
+function entryHash(prevHash, fields, mac) {
+	checkHash(prevHash, "prevHash");
+	checkHash(mac, "mac");
+	return createHash("sha256").update(CHAIN_DOMAIN).update(prevHash).update(encodeFields(fields)).update(mac).digest();
+}
+/** An entry's MAC and hash, as `key` writes it after `prevHash`. */
+function sealEntry(key, prevHash, fields) {
+	if (fields.author !== key.author || fields.keyId !== key.keyId) throw new Error(`an entry by ${fields.author} under ${fields.keyId} cannot be sealed with ${key.keyId}`);
+	const mac = entryMac(key.key, prevHash, fields);
+	return {
+		mac,
+		hash: entryHash(prevHash, fields, mac)
+	};
+}
+/**
+* Check a run of entries, oldest first: that the numbers run on from
+* `startSeq` without a gap, that each links to the hash before it, that each
+* hash is its entry's, and that each entry carries a MAC from one of `keys`.
+*
+* An author whose key the verifier does not hold fails every entry it wrote,
+* unless it is named in `chainOnly`: then its entries are checked for their
+* place in the chain only, and `authenticated` counts the rest. That is a
+* partial verdict, for a caller that has the other author check its own
+* entries over the same prefix; the public chain alone proves nothing about
+* who wrote an entry, since anyone who can insert a row can link it.
+*/
+function verifyEntries(entries, { startSeq = 0n, startPrevHash = GENESIS_HASH, keys, chainOnly = [] }) {
+	const authors = new Set(keys.map((key) => key.author));
+	let expectedSeq = startSeq;
+	let previous = startPrevHash;
+	let authenticated = 0;
+	for (const entry of entries) {
+		const fail = (reason) => ({
+			ok: false,
+			failedAtSeq: entry.seq,
+			reason
+		});
+		if (entry.seq !== expectedSeq) return fail(`sequence gap: expected seq ${expectedSeq}, found ${entry.seq}`);
+		if (!equal(entry.prevHash, previous)) return fail("prev_hash does not match the entry before");
+		if (entry.mac.length !== 32 || !equal(entryHash(entry.prevHash, entry, entry.mac), entry.hash)) return fail("hash does not match the entry");
+		if (authors.has(entry.author)) {
+			const key = keys.find((candidate) => candidate.keyId === entry.keyId && candidate.author === entry.author);
+			if (key === void 0) return fail(`written under ${entry.keyId}, a key this verifier does not hold`);
+			if (!equal(entryMac(key.key, entry.prevHash, entry), entry.mac)) return fail(`not written by the ${entry.author}: its MAC does not match`);
+			authenticated += 1;
+		} else if (!chainOnly.includes(entry.author)) return fail(`written as the ${entry.author}, whose keys this verifier does not hold`);
+		previous = entry.hash;
+		expectedSeq = entry.seq + 1n;
+	}
+	return {
+		ok: true,
+		entries: entries.length,
+		head: previous,
+		nextSeq: expectedSeq,
+		authenticated
+	};
+}
+function checkHash(value, what) {
+	if (value.length !== 32) throw new Error(`${what} must be 32 bytes, got ${value.length}`);
+}
+function equal(a, b) {
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+//#endregion
+export { GENESIS_HASH, HASH_BYTES, LOG_FORMAT, deriveLogKey, encodeFields, entryHash, entryMac, sealEntry, verifyEntries };

package/dist/dotenv.d.ts

@@ -0,0 +1,45 @@
+//#region src/dotenv.d.ts
+/**
+ * A small .env parser, for bulk import, and its inverse, for export.
+ *
+ * Deliberately hand-written rather than pulled from npm: this runs inside the
+ * service that holds every credential we own, and the whole grammar is about
+ * thirty lines. The server parses and the CLI formats with this one module,
+ * so `coffre export` output always imports back unchanged.
+ *
+ * Supported: `KEY=value`, `export KEY=value`, single and double quoting,
+ * escapes inside double quotes, `#` comments, blank lines, and surrounding
+ * whitespace. NOT supported: multi-line values and variable interpolation --
+ * both are reported as errors rather than being silently mangled.
+ */
+export type ParsedEntry = {
+  key: string;
+  value: string;
+  line: number;
+};
+export type ParseProblem = {
+  line: number;
+  text: string;
+  reason: string;
+};
+export type ParseResult = {
+  entries: ParsedEntry[];
+  problems: ParseProblem[];
+};
+export declare function parseDotenv(input: string): ParseResult;
+/**
+ * Write entries as a .env file that `parseDotenv` reads back exactly.
+ *
+ * Plain values stay bare; anything else is single-quoted, which is literal;
+ * values holding a quote or a line break are double-quoted with the four
+ * escapes the parser knows (`\\`, `\"`, `\n`, `\r`).
+ */
+export declare function formatDotenv(entries: Iterable<readonly [key: string, value: string]>): string;
+/**
+ * Write entries as POSIX shell `export` statements, for
+ * `eval "$(coffre export … --format shell)"`. Single quotes are the only
+ * shell quoting with no expansion inside; a single quote itself is written
+ * as `'\''`.
+ */
+export declare function formatShellExports(entries: Iterable<readonly [key: string, value: string]>): string;
+//#endregion