@coffre/core 0.0.0 → 0.1.1

package/src/access.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 const PERMISSIONS = [
+  'secret.read',
+  'secret.write',
+  'secret.archive',
+  'audit.read',
+  'environment.manage',
+  'grant.manage',
+  'project.manage',
+] as const;
+
+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 const PROJECT_ONLY_PERMISSIONS: readonly Permission[] = [
+  'environment.manage',
+  'grant.manage',
+  'project.manage',
+];
+
+export 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],
+  },
+} as const satisfies Record<string, {
+  name: string;
+  description: string;
+  permissions: readonly Permission[];
+}>;
+
+export type Role = keyof typeof ROLES;
+
+export const ROLE_NAMES = Object.keys(ROLES) as Role[];
+
+export function isRole(value: string): value is Role {
+  return Object.hasOwn(ROLES, value);
+}
+
+export function roleGrants(role: Role, permission: Permission): boolean {
+  return (ROLES[role].permissions as readonly Permission[]).includes(permission);
+}
+
+/** Roles that hold a project-only permission can only be granted on a project. */
+export function assignableToEnvironment(role: Role): boolean {
+  return !ROLES[role].permissions.some((permission) =>
+    PROJECT_ONLY_PERMISSIONS.includes(permission),
+  );
+}
+
+/** 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 function allows(holder: Holdings, permission: Permission, place: Place): boolean {
+  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>`. */
+export function isSyncPrincipal(principal: string): boolean {
+  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.
+ */
+export function mayManageAccess(
+  actor: Holdings,
+  subject: string,
+  change: Place & { role: Role | null },
+): boolean {
+  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);
+}

package/src/audit/chain.ts

@@ -0,0 +1,207 @@
+import { createHash, createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+
+/**
+ * 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 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. */
+export const HASH_BYTES = 32;
+
+/** The `prev_hash` of the first entry. */
+export const GENESIS_HASH: Buffer = Buffer.alloc(HASH_BYTES, 0);
+
+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;
+};
+
+const FIELD_ORDER = [
+  'seq',
+  'author',
+  'keyId',
+  'occurredAt',
+  'actor',
+  'action',
+  'decision',
+  'code',
+  'subjectPrincipal',
+  'projectId',
+  'environmentId',
+  'secretId',
+  'secretVersionId',
+  'operationId',
+  'requestId',
+  'sourceIp',
+  'relatedSeq',
+  'metadata',
+] as const satisfies readonly (keyof LogFields)[];
+
+/**
+ * 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 function encodeFields(fields: LogFields): Buffer {
+  const parts: Buffer[] = [];
+  for (const name of FIELD_ORDER) {
+    const raw = fields[name];
+    const header = Buffer.alloc(4);
+    if (raw === undefined) 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);
+}
+
+/** 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 function deriveLogKey(author: Author, secret: Uint8Array): LogKey {
+  if (secret.length < 32) throw new Error('a log key needs at least 32 bytes of secret');
+  const key = Buffer.from(hkdfSync('sha256', secret, new Uint8Array(0), `coffre.audit.${author}.v2`, 32));
+  const fingerprint = createHash('sha256').update(key).digest('hex').slice(0, 16);
+  return { author, keyId: `${author}:${fingerprint}`, key };
+}
+
+/** The MAC of an entry, under its author's key. */
+export function entryMac(key: Buffer, prevHash: Buffer, fields: LogFields): Buffer {
+  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. */
+export function entryHash(prevHash: Buffer, fields: LogFields, mac: Buffer): Buffer {
+  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`. */
+export function sealEntry(key: LogKey, prevHash: Buffer, fields: LogFields): { mac: Buffer; hash: Buffer } {
+  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) };
+}
+
+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 function verifyEntries(
+  entries: readonly StoredEntry[],
+  {
+    startSeq = 0n,
+    startPrevHash = GENESIS_HASH,
+    keys,
+    chainOnly = [],
+  }: { startSeq?: bigint; startPrevHash?: Buffer; keys: readonly LogKey[]; chainOnly?: readonly Author[] },
+): ChainVerification {
+  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: string) => ({ ok: false as const, 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 !== HASH_BYTES || !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 === undefined) 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: Buffer, what: string): void {
+  if (value.length !== HASH_BYTES) throw new Error(`${what} must be ${HASH_BYTES} bytes, got ${value.length}`);
+}
+
+function equal(a: Buffer, b: Buffer): boolean {
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/src/checkpoint.ts

@@ -0,0 +1,13 @@
+import type { Checkpoint } from './vault.ts';
+
+/** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
+export function checkpointMessage(checkpoint: Omit<Checkpoint, 'signature' | 'keyId'>): Uint8Array<ArrayBuffer> {
+  const { seq, hash, signedAt } = checkpoint;
+  return new Uint8Array(new TextEncoder().encode(`coffre.checkpoint.v3|${seq}|${hash}|${signedAt}`));
+}
+
+/** Whether `checkpoint` was signed by the key whose raw public half is `publicKey`. */
+export async function verifyCheckpoint(checkpoint: Checkpoint, publicKey: string): Promise<boolean> {
+  const key = await crypto.subtle.importKey('raw', new Uint8Array(Buffer.from(publicKey, 'base64')), { name: 'Ed25519' }, false, ['verify']);
+  return crypto.subtle.verify('Ed25519', key, new Uint8Array(Buffer.from(checkpoint.signature, 'base64')), checkpointMessage(checkpoint));
+}

package/src/context.ts

@@ -0,0 +1,54 @@
+/**
+ * The binding context for a secret's ciphertext.
+ *
+ * This is the AES-GCM additional authenticated data (AAD). It ties a ciphertext
+ * to exactly one (project, environment, secret) triple, so a ciphertext lifted
+ * out of the `dev` environment row and dropped into the `prod` row fails to
+ * decrypt rather than silently succeeding.
+ *
+ * These are immutable UUIDs, never names. Binding to `project/environment/key`
+ * names would mean that renaming an environment or a secret key makes every
+ * existing ciphertext permanently undecryptable.
+ */
+export type SecretContext = {
+  projectId: string;
+  environmentId: string;
+  secretId: string;
+};
+
+/**
+ * Version prefix for the AAD encoding. If the encoding ever changes, this
+ * changes with it, and old ciphertexts keep decrypting under the old rule.
+ */
+export const AAD_VERSION = 'coffre.aad.v1';
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function assertUuid(value: string, field: string): void {
+  if (typeof value !== 'string' || !UUID_RE.test(value)) {
+    throw new Error(`context.${field} must be a lowercase UUID, got: ${String(value)}`);
+  }
+}
+
+/** Throw unless every field is a lowercase UUID. */
+export function checkContext(ctx: SecretContext): void {
+  assertUuid(ctx.projectId, 'projectId');
+  assertUuid(ctx.environmentId, 'environmentId');
+  assertUuid(ctx.secretId, 'secretId');
+}
+
+/**
+ * Encode a context into AAD bytes.
+ *
+ * Every field is validated as a UUID first, which is what makes joining with
+ * `|` unambiguous: a UUID cannot contain the separator, so no two distinct
+ * contexts can encode to the same bytes.
+ */
+export function encodeAad(ctx: SecretContext): Buffer {
+  checkContext(ctx);
+  return Buffer.from(
+    `${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}`,
+    'utf8',
+  );
+}

package/src/dotenv.ts

@@ -0,0 +1,242 @@
+/**
+ * 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[];
+};
+
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+export function parseDotenv(input: string): ParseResult {
+  const entries: ParsedEntry[] = [];
+  const problems: ParseProblem[] = [];
+  const seen = new Set<string>();
+
+  // Split on all three line-ending conventions. Splitting on /\r?\n/ alone
+  // leaves a lone \r inside the value, which silently swallows the following
+  // key into the preceding secret -- corruption with no error.
+  const lines = input.split(/\r\n|\n|\r/);
+
+  for (let index = 0; index < lines.length; index++) {
+    const lineNumber = index + 1;
+    const raw = lines[index];
+    const trimmed = raw.trim();
+
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    const withoutExport = trimmed.startsWith('export ')
+      ? trimmed.slice('export '.length).trim()
+      : trimmed;
+
+    const equals = withoutExport.indexOf('=');
+    if (equals === -1) {
+      problems.push({ line: lineNumber, text: trimmed, reason: 'no "=" on this line' });
+      continue;
+    }
+
+    const key = withoutExport.slice(0, equals).trim();
+    if (!KEY_RE.test(key)) {
+      problems.push({
+        line: lineNumber,
+        text: key,
+        reason: 'key must match ^[A-Za-z_][A-Za-z0-9_]*$',
+      });
+      continue;
+    }
+
+    let rest = withoutExport.slice(equals + 1).trim();
+    let value: string;
+
+    if (rest.startsWith('"')) {
+      const closing = findClosingQuote(rest, '"');
+      if (closing === -1) {
+        problems.push({
+          line: lineNumber,
+          text: key,
+          reason: 'unterminated double quote (multi-line values are not supported)',
+        });
+        continue;
+      }
+      value = unescapeDoubleQuoted(rest.slice(1, closing));
+      // Anything other than whitespace or a comment after the closing quote
+      // means the line is not what its author thought it was. Rejecting beats
+      // silently discarding part of a credential.
+      if (trailingIsSignificant(rest.slice(closing + 1))) {
+        problems.push({
+          line: lineNumber,
+          text: key,
+          reason: 'unexpected text after the closing quote',
+        });
+        continue;
+      }
+    } else if (rest.startsWith("'")) {
+      const closing = rest.indexOf("'", 1);
+      if (closing === -1) {
+        problems.push({
+          line: lineNumber,
+          text: key,
+          reason: 'unterminated single quote (multi-line values are not supported)',
+        });
+        continue;
+      }
+      // Single quotes are literal, as in a shell: no escapes inside them.
+      value = rest.slice(1, closing);
+      if (trailingIsSignificant(rest.slice(closing + 1))) {
+        problems.push({
+          line: lineNumber,
+          text: key,
+          reason: 'unexpected text after the closing quote',
+        });
+        continue;
+      }
+    } else {
+      // Unquoted: strip a trailing comment, then trailing whitespace.
+      const comment = rest.indexOf(' #');
+      if (comment !== -1) rest = rest.slice(0, comment);
+      value = rest.trim();
+    }
+
+    // A NUL byte cannot survive being put in a process environment: execve
+    // truncates at the first one, so `coffre run` would inject a silently
+    // shortened secret. Refuse it here rather than store something that will
+    // be wrong only at the point of use.
+    if (value.includes('\u0000')) {
+      problems.push({
+        line: lineNumber,
+        text: key,
+        reason: 'value contains a NUL byte, which cannot be passed in an environment',
+      });
+      continue;
+    }
+
+    if (seen.has(key)) {
+      problems.push({ line: lineNumber, text: key, reason: 'duplicate key in this file' });
+      continue;
+    }
+    seen.add(key);
+
+    entries.push({ key, value, line: lineNumber });
+  }
+
+  return { entries, problems };
+}
+
+/** True when what follows a closing quote is neither whitespace nor a comment. */
+function trailingIsSignificant(rest: string): boolean {
+  const trimmed = rest.trim();
+  return trimmed !== '' && !trimmed.startsWith('#');
+}
+
+function findClosingQuote(text: string, quote: string): number {
+  for (let index = 1; index < text.length; index++) {
+    if (text[index] === '\\') {
+      index++;
+      continue;
+    }
+    if (text[index] === quote) return index;
+  }
+  return -1;
+}
+
+/**
+ * Expand escapes inside a double-quoted value.
+ *
+ * Deliberately minimal: only the escapes that are necessary. `\n` and `\r`
+ * because multi-line values (PEM keys) cannot otherwise be expressed on one
+ * line, and `\\` `\"` `\'` because quoting needs them.
+ *
+ * EVERYTHING ELSE IS PRESERVED VERBATIM, backslash included. The obvious
+ * implementation -- returning the character and dropping the backslash for
+ * unknown escapes -- silently mangles credentials: `"C:\path\to\file"` came
+ * out as `C:path<TAB>ofile`, and `"\d+\w"` as `d+w`. A secrets store that
+ * quietly rewrites what you gave it is worse than one that refuses.
+ *
+ * A value that should contain no interpretation at all belongs in single
+ * quotes, which are literal.
+ */
+function unescapeDoubleQuoted(text: string): string {
+  return text.replace(/\\(.)/g, (match, character: string) => {
+    switch (character) {
+      case 'n':
+        return '\n';
+      case 'r':
+        return '\r';
+      case '\\':
+      case '"':
+      case "'":
+        return character;
+      default:
+        return match;
+    }
+  });
+}
+
+/** Values that read the same unquoted: no spaces, quotes, `#`, `$` or backslashes. */
+const PLAIN_VALUE = /^[A-Za-z0-9_./:@+,=%?-]*$/;
+
+/**
+ * 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 function formatDotenv(entries: Iterable<readonly [key: string, value: string]>): string {
+  let out = '';
+  for (const [key, value] of entries) {
+    assertWritable(key, value);
+    out += `${key}=${quoteDotenv(value)}\n`;
+  }
+  return out;
+}
+
+function assertWritable(key: string, value: string): void {
+  if (!KEY_RE.test(key)) throw new Error(`${JSON.stringify(key)} is not a valid variable name`);
+  if (value.includes('\u0000')) throw new Error(`${key} contains a NUL byte`);
+}
+
+function quoteDotenv(value: string): string {
+  if (PLAIN_VALUE.test(value)) return value;
+  if (!/['\n\r]/.test(value)) return `'${value}'`;
+  const escaped = value.replace(/[\\"\n\r]/g, (character) => {
+    switch (character) {
+      case '\n':
+        return '\\n';
+      case '\r':
+        return '\\r';
+      default:
+        return `\\${character}`;
+    }
+  });
+  return `"${escaped}"`;
+}
+
+/**
+ * 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 function formatShellExports(entries: Iterable<readonly [key: string, value: string]>): string {
+  let out = '';
+  for (const [key, value] of entries) {
+    assertWritable(key, value);
+    out += `export ${key}='${value.replaceAll("'", "'\\''")}'\n`;
+  }
+  return out;
+}