@ultimat3/core 1.1.0 → 2.0.0

package/src/secrets-errors.ts

@@ -0,0 +1,143 @@
+// Single responsibility: the seven X_SECRETS_* conditions and the errors that carry them. Split
+// from `secrets.ts` so the crypto module reads as crypto — and there are seven codes rather than
+// one "secrets are broken" because each names a different thing an operator did and a different
+// command that undoes it. No error here ever carries a key, a ciphertext or a decrypted value.
+
+import { registerErrorCodes } from './error-codes';
+import { UltimateError } from './errors';
+
+/** Codes `@ultimat3/core` owns for the encrypted-secrets file. */
+export const SECRETS_ERROR_CODES = [
+  'X_SECRETS_KEY_MISSING',
+  'X_SECRETS_KEY_INVALID',
+  'X_SECRETS_KEY_MISMATCH',
+  'X_SECRETS_FILE_MISSING',
+  'X_SECRETS_FILE_INVALID',
+  'X_SECRETS_TAMPERED',
+  'X_SECRETS_PLAINTEXT_INVALID',
+] as const;
+
+export type SecretsErrorCode = (typeof SECRETS_ERROR_CODES)[number];
+
+const SECRETS_ERROR_TITLES: Readonly<Record<SecretsErrorCode, string>> = {
+  X_SECRETS_KEY_MISSING: 'no master key for the encrypted secrets file',
+  X_SECRETS_KEY_INVALID: 'the master key is not 32 bytes of hex',
+  X_SECRETS_KEY_MISMATCH: 'the secrets file was sealed with a different master key',
+  X_SECRETS_FILE_MISSING: 'the encrypted secrets file does not exist',
+  X_SECRETS_FILE_INVALID: 'the encrypted secrets file is not a readable envelope',
+  X_SECRETS_TAMPERED: 'the secrets file failed its authentication tag',
+  X_SECRETS_PLAINTEXT_INVALID: 'the decrypted secrets are not a flat map of env values',
+};
+
+// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
+// module that throws them ship together: `registerErrorCodes` is the documented way a set of codes
+// joins the registry, and it raises `X_ERROR_CODE_DUPLICATE` if anything else ever claims one.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(SECRETS_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+/**
+ * No key in the environment and none on disk, while an encrypted file exists. Deliberately fatal
+ * rather than a warning: booting without the secrets a deploy was configured with produces an app
+ * that authenticates against nothing and reports itself healthy.
+ */
+export class SecretsKeyMissingError extends UltimateError {
+  constructor(input: { envVar: string; keyPath: string }) {
+    super({
+      code: 'X_SECRETS_KEY_MISSING',
+      cause: `${input.envVar} is unset and ${input.keyPath} does not exist, so nothing can open the encrypted secrets`,
+      fix: `export ${input.envVar}="$(cat ${input.keyPath})"   # in a repo that has no key yet: x secrets init`,
+      meta: { keyPath: input.keyPath },
+    });
+  }
+}
+
+/** Key material that is not 64 lowercase hex characters. A truncated paste is the usual cause. */
+export class SecretsKeyInvalidError extends UltimateError {
+  constructor(input: { at: string; found: number; expected: number }) {
+    super({
+      code: 'X_SECRETS_KEY_INVALID',
+      cause: `the master key in ${input.at} is ${input.found} character(s); an AES-256 key is ${input.expected} lowercase hex characters`,
+      fix: `export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"   # the key file holds the ${input.expected} characters verbatim, no newline of its own`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * A well-formed key that is not the one this file was sealed with. Distinguishable from tampering
+ * only because the envelope carries a key id — a domain-separated SHA-256 of the key, which is
+ * safe to commit and is what turns "it will not decrypt" into two different instructions.
+ */
+export class SecretsKeyMismatchError extends UltimateError {
+  constructor(input: { at: string; keyAt: string; sealedWith: string; found: string }) {
+    super({
+      code: 'X_SECRETS_KEY_MISMATCH',
+      cause: `${input.at} was sealed with master key ${input.sealedWith} and ${input.keyAt} holds ${input.found}`,
+      fix: `git checkout -- ${input.at}   # or point ULTIMATE_SECRETS_KEY at the key whose id is ${input.sealedWith}`,
+      meta: { at: input.at, sealedWith: input.sealedWith, found: input.found },
+    });
+  }
+}
+
+/** No encrypted file at all — this repo has never run `x secrets init`. */
+export class SecretsFileMissingError extends UltimateError {
+  constructor(input: { at: string }) {
+    super({
+      code: 'X_SECRETS_FILE_MISSING',
+      cause: `${input.at} does not exist, so this app declares no encrypted secrets`,
+      fix: 'x secrets init',
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * The envelope itself will not parse: not JSON, an unknown version or algorithm, a header field
+ * that is not base64, or a body too short to hold a 16-byte tag. Separate from `X_SECRETS_TAMPERED`
+ * because nothing here got as far as authentication — this is a file a merge or an editor mangled.
+ */
+export class SecretsFileInvalidError extends UltimateError {
+  constructor(input: { at: string; reason: string }) {
+    super({
+      code: 'X_SECRETS_FILE_INVALID',
+      cause: `${input.at} ${input.reason}`,
+      fix: `git checkout -- ${input.at}   # this file is written only by x secrets, never by hand`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * The AES-256-GCM tag rejected the ciphertext or the header bound into it as AAD. Under a key whose
+ * id already matched, that means the committed bytes changed after they were sealed — a bad merge,
+ * a partial write, or an edit. Silent garbage is the alternative this code exists to prevent.
+ */
+export class SecretsTamperedError extends UltimateError {
+  constructor(input: { at: string }) {
+    super({
+      code: 'X_SECRETS_TAMPERED',
+      cause: `the AES-256-GCM authentication tag rejected ${input.at}: the ciphertext or its header changed after it was sealed`,
+      fix: `git checkout -- ${input.at}   # then confirm the restored file opens: x secrets show --json`,
+      meta: { at: input.at },
+    });
+  }
+}
+
+/**
+ * Decryption succeeded and the payload is not what a secrets file holds. Reachable two ways: an
+ * `x secrets edit` buffer saved as something other than a flat object, and a value that is not a
+ * non-empty string. Both are refused BEFORE sealing, so a file that opens always installs.
+ */
+export class SecretsPlaintextInvalidError extends UltimateError {
+  constructor(input: { at: string; reason: string }) {
+    super({
+      code: 'X_SECRETS_PLAINTEXT_INVALID',
+      cause: `the secrets for ${input.at} ${input.reason}`,
+      fix: 'x secrets edit   # the buffer is one flat JSON object: {"SESSION_SECRET": "s3cr3t"} — env var names to non-empty strings',
+      meta: { at: input.at },
+    });
+  }
+}

package/src/secrets-store.ts

@@ -0,0 +1,173 @@
+// Single responsibility: where the two secrets files live, how the master key is found, and the
+// ONE path from a decrypted value to a `defineEnv`-declared variable — `installSecrets()` writes
+// each value into the process environment, under its own name, only where the real environment has
+// nothing. `secrets.ts` owns the envelope; this owns the filesystem and `process.env`.
+
+// `node:fs` sync, by necessity twice over: Bun.write takes no mode, and a world-readable master key
+// is the whole failure this file exists to prevent — and `installSecrets()` runs once, at boot,
+// before the process is serving anything, so there is nothing for an async read to overlap with.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+// Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import type { SecretValues } from './secrets';
+import { masterKeyId, openSecrets, parseMasterKey, sealSecrets } from './secrets';
+import { SecretsFileMissingError, SecretsKeyMissingError } from './secrets-errors';
+
+/** Committed. Encrypted at rest, diffable, and the only file `x secrets` writes into the repo. */
+export const SECRETS_FILE = 'secrets.enc.json';
+/** Never committed — `x secrets init` writes the ignore rule before it writes this. */
+export const SECRETS_KEY_FILE = '.secrets.key';
+/** Read first, so a container gets its key from the platform's secret store and never from a file. */
+export const SECRETS_KEY_ENV = 'ULTIMATE_SECRETS_KEY';
+/** Owner read/write. A key file the rest of the box can read is a key file that has leaked. */
+export const SECRETS_KEY_MODE = 0o600;
+
+export type MasterKeySource = 'env' | 'file';
+
+export interface MasterKeyRef {
+  readonly hex: string;
+  readonly source: MasterKeySource;
+  /** The env var name or the file path, for an error's `cause` — never the key itself. */
+  readonly at: string;
+}
+
+type EnvRecord = Record<string, string | undefined>;
+
+export const secretsPath = (root: string): string => join(root, SECRETS_FILE);
+export const masterKeyPath = (root: string): string => join(root, SECRETS_KEY_FILE);
+export const secretsFileExists = (root: string): boolean => existsSync(secretsPath(root));
+
+/**
+ * Env var first, key file second. That order is what makes one image run everywhere: a container
+ * is handed `ULTIMATE_SECRETS_KEY` and never ships a key file, while a checkout has the file and
+ * needs no exported variable.
+ */
+export function findMasterKey(
+  root: string,
+  env: EnvRecord = process.env,
+): MasterKeyRef | undefined {
+  const fromEnv = env[SECRETS_KEY_ENV];
+  if (fromEnv !== undefined && fromEnv.trim().length > 0) {
+    return { hex: fromEnv.trim(), source: 'env', at: SECRETS_KEY_ENV };
+  }
+  const path = masterKeyPath(root);
+  if (!existsSync(path)) return undefined;
+  return { hex: readFileSync(path, 'utf-8').trim(), source: 'file', at: path };
+}
+
+export function requireMasterKey(root: string, env: EnvRecord = process.env): MasterKeyRef {
+  const found = findMasterKey(root, env);
+  if (found !== undefined) return found;
+  throw new SecretsKeyMissingError({ envVar: SECRETS_KEY_ENV, keyPath: masterKeyPath(root) });
+}
+
+/** The key's public id. Safe to print, safe to commit — it is what names a rotation in a diff. */
+export const masterKeyIdOf = (key: MasterKeyRef): Promise<string> =>
+  masterKeyId(parseMasterKey(key.hex, key.at));
+
+/** Decrypt the committed file. `X_SECRETS_FILE_MISSING` when there is none — never an empty map. */
+export async function readSecretsFile(root: string, key: MasterKeyRef): Promise<SecretValues> {
+  const path = secretsPath(root);
+  if (!existsSync(path)) throw new SecretsFileMissingError({ at: path });
+  return openSecrets(readFileSync(path, 'utf-8'), key.hex, { file: path, key: key.at });
+}
+
+/** Seal and commit. The only writer of `secrets.enc.json`; plaintext never reaches this path. */
+export async function writeSecretsFile(
+  root: string,
+  values: SecretValues,
+  key: MasterKeyRef,
+): Promise<string> {
+  const path = secretsPath(root);
+  await Bun.write(path, await sealSecrets(values, key.hex, { file: path, key: key.at }));
+  return path;
+}
+
+/** Write the master key at 0600. Callers must have made the ignore rule true first. */
+export function writeMasterKeyFile(root: string, keyHex: string): string {
+  const path = masterKeyPath(root);
+  writeFileSync(path, `${keyHex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE });
+  return path;
+}
+
+export interface SecretsInstallOptions {
+  /** The app root holding `secrets.enc.json`. Defaults to the process's working directory. */
+  readonly root?: string | undefined;
+  /** Read for the key and written with the values. Defaults to `process.env`. */
+  readonly env?: EnvRecord | undefined;
+}
+
+/** Names only. A report that carried a value would be a secret in every log that printed it. */
+export interface SecretsInstallReport {
+  readonly present: boolean;
+  readonly path: string;
+  readonly keySource: MasterKeySource | undefined;
+  readonly keyId: string | undefined;
+  /** Variables this call set. */
+  readonly installed: readonly string[];
+  /** Variables the real environment already supplied, so the file's value was not used. */
+  readonly skipped: readonly string[];
+}
+
+/**
+ * Decrypt the committed secrets into the environment, then let `defineEnv` do what it already does.
+ *
+ * ```ts
+ * await installSecrets();                                   // app.config.ts, first line
+ * export const envSchema = { SESSION_SECRET: { type: 'string', secret: true } } satisfies EnvSchema;
+ * export const env = defineEnv(envSchema);
+ * ```
+ *
+ * This is the whole integration, and it is one path rather than two on purpose. A secret has one
+ * name — the env var it becomes — so it keeps one declaration (`envSchema`), one row in
+ * `.env.example`, one masker (`maskedEnvValues`), one redaction entry (`redactKeys`) and one
+ * reader (`env.SESSION_SECRET`). A `secrets.get('…')` accessor would mint values with no
+ * declaration, no type and no mask, and every one of those five would need a second implementation.
+ *
+ * The real environment always wins: a platform-injected `DATABASE_URL` beats the committed file, so
+ * the same image runs in Compose and K8s without a second secrets file per deploy. A file that does
+ * not exist is not an error — an app may declare no secrets — but a file that exists with no key to
+ * open it is `X_SECRETS_KEY_MISSING`, because booting past it produces an app that authenticates
+ * against nothing and reports itself healthy.
+ *
+ * Forgetting the `await` fails loudly rather than silently: `defineEnv` runs first and throws
+ * `X_ENV_MISSING` naming every variable the file would have supplied.
+ */
+export async function installSecrets(
+  options: SecretsInstallOptions = {},
+): Promise<SecretsInstallReport> {
+  const root = options.root ?? process.cwd();
+  const env = options.env ?? (process.env as EnvRecord);
+  const path = secretsPath(root);
+  if (!existsSync(path)) {
+    return {
+      present: false,
+      path,
+      keySource: undefined,
+      keyId: undefined,
+      installed: [],
+      skipped: [],
+    };
+  }
+  const key = requireMasterKey(root, env);
+  const values = await readSecretsFile(root, key);
+  const installed: string[] = [];
+  const skipped: string[] = [];
+  for (const [name, value] of Object.entries(values)) {
+    const current = env[name];
+    if (current === undefined || current === '') {
+      env[name] = value;
+      installed.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+  return {
+    present: true,
+    path,
+    keySource: key.source,
+    keyId: await masterKeyIdOf(key),
+    installed: installed.sort(),
+    skipped: skipped.sort(),
+  };
+}

package/src/secrets.ts

@@ -0,0 +1,292 @@
+// Single responsibility: the encrypted-secrets envelope. Seal a flat map of env values under a
+// 32-byte master key and open one back, AES-256-GCM through WebCrypto only — a fresh 12-byte IV per
+// seal, the 128-bit tag verified on open, and the envelope's own header bound in as additional
+// authenticated data so a downgraded `alg` or a swapped key id fails the tag instead of decrypting.
+
+import {
+  SecretsFileInvalidError,
+  SecretsKeyInvalidError,
+  SecretsKeyMismatchError,
+  SecretsPlaintextInvalidError,
+  SecretsTamperedError,
+} from './secrets-errors';
+
+export const SECRETS_VERSION = 1;
+export const SECRETS_ALG = 'AES-256-GCM';
+export const SECRETS_KEY_BYTES = 32;
+export const SECRETS_KEY_HEX_LENGTH = SECRETS_KEY_BYTES * 2;
+/** GCM's standard nonce. 96 bits is the size the construction is defined for; never reused. */
+export const SECRETS_IV_BYTES = 12;
+export const SECRETS_TAG_BYTES = 16;
+/** Truncated to 64 bits: enough to name a key, far too little to attack the 256-bit key behind it. */
+export const SECRETS_KEY_ID_LENGTH = 16;
+
+/** A secret's name is the env var it becomes — there is no second namespace. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+const HEX_KEY = /^[0-9a-f]+$/;
+const KEY_ID = /^[0-9a-f]{16}$/;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/** Decrypted values: env var name to value. Flat on purpose — see `installSecrets`. */
+export type SecretValues = Readonly<Record<string, string>>;
+
+/** The committed file, header first so `git diff` shows a rotation as a one-line `kid` change. */
+export interface SecretsEnvelope {
+  readonly v: number;
+  readonly alg: string;
+  /** Non-secret fingerprint of the master key this was sealed with. */
+  readonly kid: string;
+  readonly iv: string;
+  readonly ct: string;
+}
+
+/** Where each half came from, so an error names the file the reader has to act on. */
+export interface SecretsLocation {
+  /** The envelope's path, or the name of whatever produced it. */
+  readonly file: string;
+  /** The master key's origin — an env var name, or the key file's path. */
+  readonly key: string;
+}
+
+const encoder = new TextEncoder();
+
+function encodeHex(bytes: Uint8Array<ArrayBuffer>): string {
+  let out = '';
+  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
+  return out;
+}
+
+function decodeHex(hex: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1)
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
+
+// `btoa`/`atob` rather than node:buffer — both are standard globals, and a chunk loop avoids the
+// stack blow-up `String.fromCharCode(...bytes)` hits on a spread of any size.
+function encodeBase64(bytes: Uint8Array<ArrayBuffer>): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function decodeBase64(text: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** A fresh master key: 32 CSPRNG bytes, hex. The only thing that must never reach the repo. */
+export function generateMasterKey(): string {
+  return encodeHex(crypto.getRandomValues(new Uint8Array(SECRETS_KEY_BYTES)));
+}
+
+/** 64 lowercase hex characters, or `X_SECRETS_KEY_INVALID`. Whitespace is trimmed, never repaired. */
+export function parseMasterKey(raw: string, at: string): Uint8Array<ArrayBuffer> {
+  const hex = raw.trim();
+  if (hex.length !== SECRETS_KEY_HEX_LENGTH || !HEX_KEY.test(hex)) {
+    throw new SecretsKeyInvalidError({
+      at,
+      found: hex.length,
+      expected: SECRETS_KEY_HEX_LENGTH,
+    });
+  }
+  return decodeHex(hex);
+}
+
+/**
+ * The key's public name. Domain-separated so this digest can never be replayed as a digest of the
+ * key computed for any other purpose, and truncated to 16 hex characters because its only job is
+ * telling two keys apart in a committed file and in an error message.
+ */
+export async function masterKeyId(key: Uint8Array<ArrayBuffer>): Promise<string> {
+  const domain = encoder.encode('ultimate.secrets.kid.v1');
+  const material = new Uint8Array(domain.length + key.length);
+  material.set(domain, 0);
+  material.set(key, domain.length);
+  const digest = await crypto.subtle.digest('SHA-256', material);
+  return encodeHex(new Uint8Array(digest)).slice(0, SECRETS_KEY_ID_LENGTH);
+}
+
+/**
+ * The bytes the tag covers besides the ciphertext. Binding the header means an attacker who can
+ * write the file cannot downgrade `alg`, renumber `v` or claim a different `kid` without the tag
+ * catching it — the fields that decide how the body is read are authenticated with the body.
+ */
+const additionalData = (header: Omit<SecretsEnvelope, 'iv' | 'ct'>): Uint8Array<ArrayBuffer> =>
+  encoder.encode(`ultimate.secrets|v=${header.v}|alg=${header.alg}|kid=${header.kid}`);
+
+const importKey = (key: Uint8Array<ArrayBuffer>): Promise<CryptoKey> =>
+  crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+
+/**
+ * The plaintext form: one flat JSON object, keys sorted, two-space indent. Deterministic so
+ * `x secrets edit` can compare the buffer it handed the editor against the one it got back and
+ * skip the write when nothing changed — the ciphertext differs on every seal (the IV is fresh), so
+ * without this every edit session would produce a diff whether or not a value moved.
+ */
+export function serializeSecretValues(values: SecretValues): string {
+  const sorted = Object.fromEntries(Object.entries(values).sort(([a], [b]) => a.localeCompare(b)));
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+/** Flat, env-shaped and non-empty, or `X_SECRETS_PLAINTEXT_INVALID`. Runs before every seal. */
+export function assertSecretValues(value: unknown, at: string): SecretValues {
+  const refuse = (reason: string): never => {
+    throw new SecretsPlaintextInvalidError({ at, reason });
+  };
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return refuse('are not a JSON object');
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (!SECRET_NAME.test(key)) {
+      return refuse(`name "${key}", which is not an environment variable name (A-Z, 0-9, _)`);
+    }
+    if (typeof entry !== 'string') return refuse(`give "${key}" a value that is not a string`);
+    if (entry.length === 0) return refuse(`give "${key}" an empty value`);
+  }
+  return Object.freeze({ ...(value as Record<string, string>) });
+}
+
+/** The masked projection — names and lengths only. What `x secrets show` and any log may print. */
+export interface SecretSummary {
+  readonly name: string;
+  readonly length: number;
+}
+
+export function describeSecrets(values: SecretValues): readonly SecretSummary[] {
+  return Object.entries(values)
+    .map(([name, value]) => ({ name, length: value.length }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Encrypt `values` under `keyHex` and return the exact bytes the committed file holds. */
+export async function sealSecrets(
+  values: SecretValues,
+  keyHex: string,
+  at: SecretsLocation,
+): Promise<string> {
+  const checked = assertSecretValues(values, at.file);
+  const key = parseMasterKey(keyHex, at.key);
+  const header = { v: SECRETS_VERSION, alg: SECRETS_ALG, kid: await masterKeyId(key) };
+  const iv = crypto.getRandomValues(new Uint8Array(SECRETS_IV_BYTES));
+  const sealed = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: additionalData(header), tagLength: 128 },
+    await importKey(key),
+    encoder.encode(serializeSecretValues(checked)),
+  );
+  const envelope: SecretsEnvelope = {
+    ...header,
+    iv: encodeBase64(iv),
+    ct: encodeBase64(new Uint8Array(sealed)),
+  };
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}
+
+function field(record: Record<string, unknown>, name: string, at: string, bytes?: number): string {
+  const value = record[name];
+  if (typeof value !== 'string' || !BASE64.test(value) || value.length === 0) {
+    throw new SecretsFileInvalidError({ at, reason: `has no base64 "${name}" field` });
+  }
+  const decoded = decodeBase64(value);
+  if (bytes !== undefined && decoded.length !== bytes) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `has a ${decoded.length}-byte "${name}"; AES-256-GCM uses ${bytes}`,
+    });
+  }
+  return value;
+}
+
+/**
+ * Read the envelope without needing a key. Every rejection here is `X_SECRETS_FILE_INVALID`: none
+ * of it has reached authentication yet, so calling it tampering would send the reader hunting an
+ * attacker for what is a truncated write or a merge conflict marker.
+ */
+export function parseSecretsEnvelope(text: string, at: string): SecretsEnvelope {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new SecretsFileInvalidError({ at, reason: 'is not JSON' });
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new SecretsFileInvalidError({ at, reason: 'is not a JSON object' });
+  }
+  const record = parsed as Record<string, unknown>;
+  if (record['v'] !== SECRETS_VERSION) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `declares envelope version ${JSON.stringify(record['v'])}; this build seals version ${SECRETS_VERSION}`,
+    });
+  }
+  if (record['alg'] !== SECRETS_ALG) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `declares algorithm ${JSON.stringify(record['alg'])}; this build seals ${SECRETS_ALG}`,
+    });
+  }
+  const kid = record['kid'];
+  if (typeof kid !== 'string' || !KEY_ID.test(kid)) {
+    throw new SecretsFileInvalidError({ at, reason: 'has no 16-character hex "kid" field' });
+  }
+  const iv = field(record, 'iv', at, SECRETS_IV_BYTES);
+  const ct = field(record, 'ct', at);
+  if (decodeBase64(ct).length <= SECRETS_TAG_BYTES) {
+    throw new SecretsFileInvalidError({
+      at,
+      reason: `has a "ct" too short to hold a ${SECRETS_TAG_BYTES}-byte authentication tag and any content`,
+    });
+  }
+  return { v: SECRETS_VERSION, alg: SECRETS_ALG, kid, iv, ct };
+}
+
+/**
+ * Open a committed envelope. Four distinct refusals, in the order the facts become knowable: the
+ * file is unreadable, the key is malformed, the key is the wrong one (the `kid` says so before any
+ * decryption is attempted), or the tag rejected the body.
+ */
+export async function openSecrets(
+  text: string,
+  keyHex: string,
+  at: SecretsLocation,
+): Promise<SecretValues> {
+  const envelope = parseSecretsEnvelope(text, at.file);
+  const key = parseMasterKey(keyHex, at.key);
+  const kid = await masterKeyId(key);
+  if (kid !== envelope.kid) {
+    throw new SecretsKeyMismatchError({
+      at: at.file,
+      keyAt: at.key,
+      sealedWith: envelope.kid,
+      found: kid,
+    });
+  }
+  let plaintext: ArrayBuffer;
+  try {
+    plaintext = await crypto.subtle.decrypt(
+      {
+        name: 'AES-GCM',
+        iv: decodeBase64(envelope.iv),
+        additionalData: additionalData(envelope),
+        tagLength: 128,
+      },
+      await importKey(key),
+      decodeBase64(envelope.ct),
+    );
+  } catch {
+    // Deliberately no `sourceError`: WebCrypto's OperationError says nothing this code does not,
+    // and an error that wraps a crypto exception is one more object a log could try to serialize.
+    throw new SecretsTamperedError({ at: at.file });
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(plaintext));
+  } catch {
+    throw new SecretsPlaintextInvalidError({ at: at.file, reason: 'are not JSON' });
+  }
+  return assertSecretValues(decoded, at.file);
+}