@blamejs/core 0.4.1

package/lib/auth/passkey.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Passkey / WebAuthn (FIDO2) — registration + authentication primitives.
+ *
+ * Built on the vendored @simplewebauthn/server (lib/vendor/simplewebauthn-
+ * server.cjs). This file is a thin wrapper that names the surface in the
+ * framework's auth-namespace style and validates inputs through
+ * AuthError so failures are framed consistently with auth.password and
+ * auth.totp. The vendor handles CBOR parsing, attestation statement
+ * validation, COSE key conversion, and signature verification across
+ * the WebAuthn algorithm set; we don't reimplement any of it.
+ *
+ * The four phases of a WebAuthn flow:
+ *
+ *   Registration (user adds a passkey to their account):
+ *     1. server: startRegistration({ rpName, rpId, userName, userDisplayName,
+ *        excludeCredentials? }) → { challenge, … }. Server stores the
+ *        challenge in the session.
+ *     2. browser: navigator.credentials.create({ publicKey: <options> })
+ *        → registration response with attestation.
+ *     3. server: verifyRegistration({ response, expectedChallenge,
+ *        expectedOrigin, expectedRPID }) → { verified, registrationInfo:
+ *        { credential: { id, publicKey, counter }, … } }. Persist
+ *        credential.id (base64url) + credential.publicKey + counter.
+ *
+ *   Authentication (user logs in with their passkey):
+ *     1. server: startAuthentication({ rpId, userVerification? })
+ *        → { challenge, … }. Server stores challenge in session.
+ *     2. browser: navigator.credentials.get({ publicKey: <options> })
+ *        → assertion response.
+ *     3. server: lookup the credential by response.id (base64url),
+ *        then verifyAuthentication({ response, expectedChallenge,
+ *        expectedOrigin, expectedRPID, credential: { id, publicKey,
+ *        counter, transports? } }) → { verified, authenticationInfo:
+ *        { newCounter } }. Persist newCounter (clone-detection).
+ *
+ * Public API (b.auth.passkey.*):
+ *   await passkey.startRegistration(opts)        → registration options
+ *   await passkey.verifyRegistration(opts)       → { verified, registrationInfo? }
+ *   await passkey.startAuthentication(opts)      → authentication options
+ *   await passkey.verifyAuthentication(opts)     → { verified, authenticationInfo? }
+ *
+ * Framework defaults:
+ *   - attestationType: "none" — don't request attestation. Most apps
+ *     don't need it, and "direct" or "enterprise" attestation has
+ *     deployment friction (cert chains, MDS lookups). Operators who
+ *     genuinely need attestation override.
+ *   - residentKey: "preferred" — discoverable credentials when the
+ *     authenticator supports them; falls back to non-discoverable.
+ *   - userVerification: "preferred" — accept biometric / PIN when
+ *     available; fall back to presence-only.
+ *   - hints: ["client-device", "hybrid"] — surface platform
+ *     authenticators (Touch ID, Windows Hello) AND cross-device
+ *     (1Password / Bitwarden / mobile-as-roaming-authenticator).
+ *
+ * No middleware decisions made here — the wrapper does NOT touch
+ * sessions, audit, or DB. Routes integrate that themselves; the
+ * primitive stays the smallest correct surface.
+ */
+var { AuthError } = require("../framework-error");
+
+// Lazy require: the bundle is ~400 KB and not every blamejs deployment
+// uses passkeys. Loading on first call keeps boot fast for non-passkey
+// apps without forcing operators to gate the import behind a flag.
+var _wa = null;
+function _vendor() {
+  if (!_wa) _wa = require("../vendor/simplewebauthn-server.cjs");
+  return _wa;
+}
+
+function _requireString(v, name) {
+  if (typeof v !== "string" || v.length === 0) {
+    throw new AuthError("auth-passkey/missing-" + name,
+      name + " is required (non-empty string)");
+  }
+}
+
+// ---- Registration ----
+
+async function startRegistration(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  _requireString(opts.rpName, "rpName");
+  _requireString(opts.rpId, "rpId");
+  _requireString(opts.userName, "userName");
+
+  var sel = opts.authenticatorSelection || {};
+  var options = await _vendor().generateRegistrationOptions({
+    rpName:               opts.rpName,
+    rpID:                 opts.rpId,
+    userName:             opts.userName,
+    userDisplayName:      opts.userDisplayName || opts.userName,
+    attestationType:      opts.attestationType || "none",
+    excludeCredentials:   opts.excludeCredentials || [],
+    authenticatorSelection: {
+      residentKey:               sel.residentKey       || "preferred",
+      userVerification:          sel.userVerification  || "preferred",
+      authenticatorAttachment:   sel.authenticatorAttachment,
+      requireResidentKey:        sel.requireResidentKey,
+    },
+    timeout:              opts.timeout,
+    extensions:           opts.extensions,
+  });
+  // Hint the browser to surface platform + cross-device authenticators
+  // (Touch ID / Windows Hello AND 1Password / Bitwarden / phone-as-key).
+  if (!opts.hints) {
+    options.hints = ["client-device", "hybrid"];
+  } else {
+    options.hints = opts.hints;
+  }
+  return options;
+}
+
+async function verifyRegistration(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  if (!opts.response) {
+    throw new AuthError("auth-passkey/missing-response", "opts.response is required");
+  }
+  _requireString(opts.expectedChallenge, "expectedChallenge");
+  _requireString(opts.expectedOrigin, "expectedOrigin");
+  _requireString(opts.expectedRPID, "expectedRPID");
+
+  return await _vendor().verifyRegistrationResponse({
+    response:           opts.response,
+    expectedChallenge:  opts.expectedChallenge,
+    expectedOrigin:     opts.expectedOrigin,
+    expectedRPID:       opts.expectedRPID,
+    requireUserVerification: opts.requireUserVerification !== false,
+  });
+}
+
+// ---- Authentication ----
+
+async function startAuthentication(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  _requireString(opts.rpId, "rpId");
+
+  var options = await _vendor().generateAuthenticationOptions({
+    rpID:               opts.rpId,
+    userVerification:   opts.userVerification || "preferred",
+    allowCredentials:   opts.allowCredentials || [],
+    timeout:            opts.timeout,
+    extensions:         opts.extensions,
+  });
+  if (!opts.hints) {
+    options.hints = ["client-device", "hybrid"];
+  } else {
+    options.hints = opts.hints;
+  }
+  return options;
+}
+
+async function verifyAuthentication(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  if (!opts.response) {
+    throw new AuthError("auth-passkey/missing-response", "opts.response is required");
+  }
+  _requireString(opts.expectedChallenge, "expectedChallenge");
+  _requireString(opts.expectedOrigin, "expectedOrigin");
+  _requireString(opts.expectedRPID, "expectedRPID");
+  if (!opts.credential || !opts.credential.id || !opts.credential.publicKey) {
+    throw new AuthError("auth-passkey/missing-credential",
+      "opts.credential { id, publicKey, counter? } is required");
+  }
+
+  return await _vendor().verifyAuthenticationResponse({
+    response:           opts.response,
+    expectedChallenge:  opts.expectedChallenge,
+    expectedOrigin:     opts.expectedOrigin,
+    expectedRPID:       opts.expectedRPID,
+    credential:         {
+      id:         opts.credential.id,
+      publicKey:  opts.credential.publicKey,
+      counter:    opts.credential.counter || 0,
+      transports: opts.credential.transports,
+    },
+    requireUserVerification: opts.requireUserVerification !== false,
+  });
+}
+
+module.exports = {
+  startRegistration:    startRegistration,
+  verifyRegistration:   verifyRegistration,
+  startAuthentication:  startAuthentication,
+  verifyAuthentication: verifyAuthentication,
+};

package/lib/auth/password.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Argon2id password hashing — public framework primitive.
+ *
+ * Different concern from lib/vault-wrap.js, which also uses Argon2id but
+ * for KEK derivation (the output is a KEY used to AEAD-wrap the vault
+ * file). This module is for application-layer password storage: the
+ * output is a verifiable digest in PHC format, never decrypted, used
+ * for "is this the password the user originally set?".
+ *
+ * Public API:
+ *
+ *   await auth.password.hash(plain, opts?)        → string (PHC format)
+ *   await auth.password.verify(hash, plain)       → boolean
+ *   auth.password.needsRehash(hash, opts?)        → boolean
+ *
+ * The PHC string captures the algorithm + parameters + salt + digest:
+ *
+ *   $argon2id$v=19$m=65536,t=3,p=4$<base64-salt>$<base64-hash>
+ *
+ * That string is what callers store in the database. verify() parses
+ * it to recover the parameters, recomputes the digest with the
+ * supplied plaintext, and timing-safe compares.
+ *
+ * Defaults (memoryCost=64 MiB, timeCost=3, parallelism=4) target
+ * ~250–500ms on commodity 2026 hardware — painful for offline brute
+ * force, tolerable inside a login latency budget. Operators with
+ * tighter budgets (or beefier hardware) tune via opts; needsRehash
+ * surfaces when stored hashes lag behind the current defaults so the
+ * caller can transparently rehash on next successful login.
+ *
+ * Validation posture:
+ *   - plain must be a non-empty string. Empty/whitespace passwords
+ *     are operator bugs (UI should reject) — failing here surfaces
+ *     them before they hit the DB.
+ *   - plain length is capped at 4096 bytes (UTF-8). Same cap as the
+ *     vault-wrap passphrase. A 5 GiB string fed to Argon2 would peg
+ *     the box for minutes; the cap is sanity, not security.
+ *   - hash must be a non-empty string starting with `$argon2id$`.
+ *     Other Argon2 variants (`$argon2i$` / `$argon2d$`) are out of
+ *     spec for this framework — verify() returns false rather than
+ *     attempting to validate them. Callers using needsRehash on a
+ *     non-id hash get true (forces rehash on next login).
+ *
+ * Errors are AuthError(code, message) with permanent=true. A failed
+ * verify is NOT an error — it returns false. Errors are reserved for
+ * "the call shape was wrong" (empty plain, oversize plain).
+ */
+var argon2 = require("../vendor/argon2");
+var { AuthError } = require("../framework-error");
+
+// Tuning targets ~250–500ms on commodity 2026 hardware. memoryCost
+// is in KiB per Argon2's parameter convention.
+var DEFAULT_PARAMS = Object.freeze({
+  memoryCost:  65536,    // 64 MiB
+  timeCost:    3,
+  parallelism: 4,
+});
+
+var MAX_PLAINTEXT_BYTES = 4096;
+
+function _validatePlain(plain) {
+  if (typeof plain !== "string" || plain.length === 0) {
+    throw new AuthError("auth-password/invalid-plain",
+      "auth.password.hash requires a non-empty string");
+  }
+  if (Buffer.byteLength(plain, "utf8") > MAX_PLAINTEXT_BYTES) {
+    throw new AuthError("auth-password/plain-too-large",
+      "plaintext exceeds " + MAX_PLAINTEXT_BYTES + " bytes (UTF-8)");
+  }
+}
+
+function _resolveParams(opts) {
+  var p = Object.assign({}, DEFAULT_PARAMS, opts || {});
+  if (typeof p.memoryCost !== "number" || p.memoryCost < 1024) {
+    throw new AuthError("auth-password/bad-params",
+      "memoryCost must be >= 1024 KiB (1 MiB)");
+  }
+  if (typeof p.timeCost !== "number" || p.timeCost < 1) {
+    throw new AuthError("auth-password/bad-params", "timeCost must be >= 1");
+  }
+  if (typeof p.parallelism !== "number" || p.parallelism < 1) {
+    throw new AuthError("auth-password/bad-params", "parallelism must be >= 1");
+  }
+  return p;
+}
+
+async function hash(plain, opts) {
+  _validatePlain(plain);
+  var p = _resolveParams(opts);
+  return await argon2.hash(plain, {
+    type:        argon2.argon2id,
+    memoryCost:  p.memoryCost,
+    timeCost:    p.timeCost,
+    parallelism: p.parallelism,
+  });
+}
+
+async function verify(stored, plain) {
+  // verify intentionally tolerates malformed input by returning false
+  // rather than throwing — login flows already treat false as "credentials
+  // didn't match" and shouldn't have to wrap each call in try/catch.
+  if (typeof stored !== "string" || stored.length === 0) return false;
+  if (typeof plain !== "string" || plain.length === 0) return false;
+  if (!stored.indexOf || stored.indexOf("$argon2id$") !== 0) return false;
+  if (Buffer.byteLength(plain, "utf8") > MAX_PLAINTEXT_BYTES) return false;
+  try {
+    return await argon2.verify(stored, plain);
+  } catch (_e) {
+    // PHC-string parse failures from the vendor surface as throws —
+    // treat as "doesn't match" so a corrupted DB column can't break
+    // login flows with an unexpected exception type.
+    return false;
+  }
+}
+
+function needsRehash(stored, opts) {
+  if (typeof stored !== "string" || stored.indexOf("$argon2id$") !== 0) {
+    // Non-id variant or malformed — force rehash on next successful login
+    return true;
+  }
+  var p = _resolveParams(opts);
+  try {
+    return argon2.needsRehash(stored, {
+      memoryCost:  p.memoryCost,
+      timeCost:    p.timeCost,
+      parallelism: p.parallelism,
+    });
+  } catch (_e) {
+    return true;     // unparseable → rehash
+  }
+}
+
+module.exports = {
+  hash:           hash,
+  verify:         verify,
+  needsRehash:    needsRehash,
+  DEFAULT_PARAMS: DEFAULT_PARAMS,
+};

package/lib/auth/totp.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * auth.totp — auth-namespace bridge to lib/totp.js.
+ *
+ * The TOTP primitive itself is in lib/totp.js so it can be used for
+ * non-auth time-based codes (idempotency tokens, signed-link freshness
+ * windows, etc.). This file exposes the same surface under the
+ * framework's `auth.*` namespace so application code reaches it via
+ * the natural auth-feature path: `b.auth.totp.generateSecret()`.
+ *
+ * No additional logic — this is a re-export. Keeping it as a separate
+ * module (rather than `auth.totp = require("../totp")`) makes the
+ * dependency graph explicit and gives a place to layer auth-specific
+ * defaults later (e.g. an auth-namespace-only step/algorithm policy)
+ * without touching the underlying primitive.
+ */
+module.exports = require("../totp");

package/lib/auth-header.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * auth-header — construct HTTP Authorization headers for the framework's
+ * outbound consumers.
+ *
+ * The previous shape was `_authHeaders(config)` reimplemented in three
+ * places (log-stream-webhook, object-store-http-put, object-store-gcs).
+ * Each handled the same { auth, token, username, password } shape with
+ * subtly different argument names and case semantics. This module
+ * collapses the construction.
+ *
+ * Public API:
+ *
+ *   bearer(token)                      → { Authorization: "Bearer <token>" }
+ *   basic(username, password)          → { Authorization: "Basic <b64>" }
+ *   fromConfig({ auth, token, ... })   → headers object for the named auth method
+ *
+ * fromConfig accepts:
+ *
+ *   { auth: "none" }                                → {}
+ *   { auth: "bearer", token }                       → bearer(token)
+ *   { auth: "basic",  username, password }          → basic(username, password)
+ *
+ * Anything else throws AuthHeaderError. The "header" pass-through mode
+ * that consumers used to wedge into _authHeaders is NOT auth-header's job
+ * — that's just header merging. Consumers do `Object.assign({}, config.headers)`
+ * themselves and combine the two layers at the call site.
+ *
+ * Why this is a separate primitive vs. a helper inside http-client:
+ *   - Some callers (log-stream-local) might emit auth headers without
+ *     going through http-client (e.g. signed-URL inputs to a token).
+ *   - Keeping it pure-string-construction with no I/O makes it test-only
+ *     in 0ms and reusable from non-network contexts.
+ */
+
+var { FrameworkError } = require("./framework-error");
+
+class AuthHeaderError extends FrameworkError {
+  constructor(message, code) {
+    super(message, code || "auth-header/invalid");
+    this.name = "AuthHeaderError";
+    this.isAuthHeaderError = true;
+  }
+}
+
+function bearer(token) {
+  if (typeof token !== "string" || token.length === 0) {
+    throw new AuthHeaderError("bearer: token must be a non-empty string");
+  }
+  return { Authorization: "Bearer " + token };
+}
+
+function basic(username, password) {
+  // Accepting empty username + empty password reflects RFC 7617's
+  // tolerance — some legacy endpoints want literally "Basic <b64('::')>".
+  // We accept the cast to string but reject undefined-as-username
+  // (which would silently produce "Basic <b64('undefined:...')>").
+  if (username == null) {
+    throw new AuthHeaderError("basic: username is required (pass empty string for credential-less basic)");
+  }
+  var pwd = password == null ? "" : password;
+  var b64 = Buffer.from(String(username) + ":" + String(pwd), "utf8").toString("base64");
+  return { Authorization: "Basic " + b64 };
+}
+
+function fromConfig(config) {
+  if (!config || !config.auth || config.auth === "none") return {};
+  if (config.auth === "bearer") return bearer(config.token);
+  if (config.auth === "basic")  return basic(config.username, config.password);
+  throw new AuthHeaderError(
+    "unknown auth method '" + config.auth + "' (expected 'none' | 'bearer' | 'basic')",
+    "auth-header/unknown-method"
+  );
+}
+
+module.exports = {
+  bearer:           bearer,
+  basic:            basic,
+  fromConfig:       fromConfig,
+  AuthHeaderError:  AuthHeaderError,
+};

package/lib/backup/bundle.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * backup-bundle — produce an encrypted backup bundle on disk.
+ *
+ * Given a dataDir + file include list + passphrase, walks each file,
+ * encrypts its bytes via backup-crypto, computes a sha3-512 checksum
+ * of the plaintext, and emits a bundle directory:
+ *
+ *   <outDir>/manifest.json     — backup-manifest schema
+ *   <outDir>/files/<path>.enc  — per-file encrypted blob
+ *
+ * Where <path> mirrors the file's relativePath under dataDir (subdirs
+ * preserved). The manifest is the only authoritative description of
+ * the bundle's contents — a restorer reads it first, then streams
+ * each blob into staging.
+ *
+ *   await b.backupBundle.create({
+ *     dataDir:      "./data",
+ *     outDir:       "./backups/2026-04-27.bundle",  // must NOT exist
+ *     passphrase:   Buffer.from("operator passphrase"),
+ *     vaultKeyJson: "<vault.key contents>",           // string; encrypted into manifest
+ *     files: [
+ *       { relativePath: "db.enc",         kind: "raw",          required: true },
+ *       { relativePath: "db.key.enc",     kind: "raw",          required: true },
+ *       { relativePath: "vault.key",      kind: "raw",          required: false },
+ *       { relativePath: "ca.key.sealed",  kind: "vault-sealed", required: false },
+ *     ],
+ *     metadata:     { reason: "scheduled-daily" },
+ *     progressCallback: function (event) { ... },
+ *   });
+ *   // → { manifest, manifestPath, outDir, bundleSize, fileCount, durationMs }
+ *
+ * vaultKeyJson is encrypted with the operator passphrase + a fresh
+ * salt and stored in the manifest's vaultKeyEnc. With only the
+ * passphrase, a restorer on a different machine can recover the
+ * framework's vault keypair and unseal the bundle's vault-sealed
+ * files post-restore. Without the passphrase, the bundle is opaque.
+ *
+ * Per-file salts: each file gets its own fresh salt. Argon2id is
+ * memory-hard but per-file fresh-salt means an attacker who recovers
+ * one file's key from the passphrase has no leverage on other files
+ * — the salt rotation forces the full Argon2 computation per file.
+ *
+ * The bundler does NOT compress files. Operators with large datasets
+ * who want compression run their backup pipeline through their own
+ * compressor (gzip, zstd) downstream of the framework primitive.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var backupCrypto = require("./crypto");
+var backupManifest = require("./manifest");
+var { defineClass } = require("../framework-error");
+
+var BackupBundleError = defineClass("BackupBundleError", { alwaysPermanent: true });
+
+function _emit(cb, ev) {
+  if (typeof cb === "function") {
+    try { cb(ev); } catch (_e) { /* progress-callback errors are non-fatal */ }
+  }
+}
+
+// Map relativePath → encryptedPath inside the bundle. Mirrors the
+// directory structure under files/ and appends .enc so every blob
+// has a clear stride and isn't confused with the source file.
+function _encryptedPathFor(relativePath) {
+  // POSIX-normalize separators in the bundle so manifests written on
+  // Windows and Linux look the same on disk.
+  var posix = relativePath.split(path.sep).join("/");
+  return "files/" + posix + ".enc";
+}
+
+async function create(opts) {
+  var t0 = Date.now();
+  opts = opts || {};
+  if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
+    throw new BackupBundleError("backup-bundle/no-datadir",
+      "create: opts.dataDir is required and must exist");
+  }
+  if (typeof opts.outDir !== "string" || opts.outDir.length === 0) {
+    throw new BackupBundleError("backup-bundle/no-outdir",
+      "create: opts.outDir is required");
+  }
+  if (fs.existsSync(opts.outDir)) {
+    throw new BackupBundleError("backup-bundle/outdir-exists",
+      "create: outDir already exists: " + opts.outDir +
+      " (refusing to overwrite — pick a fresh path)");
+  }
+  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
+    throw new BackupBundleError("backup-bundle/no-passphrase",
+      "create: opts.passphrase is required (Buffer or string)");
+  }
+  if (typeof opts.vaultKeyJson !== "string" || opts.vaultKeyJson.length === 0) {
+    throw new BackupBundleError("backup-bundle/no-vault-key-json",
+      "create: opts.vaultKeyJson is required (the in-memory vault keypair JSON; " +
+      "use vault.getKeysJson() or read vault.key from disk)");
+  }
+  if (!Array.isArray(opts.files) || opts.files.length === 0) {
+    throw new BackupBundleError("backup-bundle/no-files",
+      "create: opts.files must be a non-empty array of include entries");
+  }
+  var passphrase = opts.passphrase;
+  var dataDir = opts.dataDir;
+  var outDir = opts.outDir;
+  var progress = opts.progressCallback;
+
+  atomicFile.ensureDir(outDir);
+  atomicFile.ensureDir(path.join(outDir, "files"));
+
+  // 1. Encrypt the vault key JSON
+  _emit(progress, { phase: "wrap_vault_key" });
+  var wrappedVk = await backupCrypto.encryptWithFreshSalt(opts.vaultKeyJson, passphrase);
+
+  // 2. Walk each include entry, encrypt the bytes, emit a blob
+  var fileEntries = [];
+  var totalBytes = 0;
+
+  for (var i = 0; i < opts.files.length; i++) {
+    var entry = opts.files[i];
+    if (!entry || typeof entry.relativePath !== "string" || entry.relativePath.length === 0) {
+      throw new BackupBundleError("backup-bundle/bad-include",
+        "create: files[" + i + "] requires { relativePath: string }");
+    }
+    if (entry.relativePath.indexOf("..") !== -1 || /^[/\\]/.test(entry.relativePath)) {
+      throw new BackupBundleError("backup-bundle/bad-include",
+        "create: files[" + i + "].relativePath must be a relative path (got '" + entry.relativePath + "')");
+    }
+    var srcPath = path.join(dataDir, entry.relativePath);
+    if (!fs.existsSync(srcPath)) {
+      if (entry.required) {
+        throw new BackupBundleError("backup-bundle/missing-required",
+          "create: required file missing: " + entry.relativePath);
+      }
+      _emit(progress, { phase: "skip_missing", relativePath: entry.relativePath });
+      continue;
+    }
+    var stat = fs.statSync(srcPath);
+    if (!stat.isFile()) {
+      // Directories aren't supported in this slice — the bundler
+      // operates on a flat list of files. Operator wanting a recursive
+      // sweep walks the dir themselves and passes the resulting list.
+      throw new BackupBundleError("backup-bundle/not-a-file",
+        "create: '" + entry.relativePath + "' is not a regular file");
+    }
+
+    _emit(progress, { phase: "read", relativePath: entry.relativePath, size: stat.size });
+    var plain = fs.readFileSync(srcPath);
+    var checksum = backupCrypto.checksum(plain);
+    var encResult = await backupCrypto.encryptWithFreshSalt(plain, passphrase);
+    var encPath = _encryptedPathFor(entry.relativePath);
+    var destFull = path.join(outDir, encPath);
+    atomicFile.ensureDir(path.dirname(destFull));
+    atomicFile.writeSync(destFull, encResult.encrypted, { fileMode: 0o600 });
+
+    var kind = entry.kind || "raw";
+    if (!backupManifest.VALID_KINDS[kind]) {
+      throw new BackupBundleError("backup-bundle/bad-kind",
+        "create: files[" + i + "].kind must be one of raw, vault-sealed, plaintext (got '" + kind + "')");
+    }
+
+    fileEntries.push({
+      relativePath:  entry.relativePath,
+      encryptedPath: encPath,
+      size:          plain.length,
+      encryptedSize: encResult.encrypted.length,
+      checksum:      checksum,
+      salt:          encResult.salt,
+      kind:          kind,
+    });
+    totalBytes += encResult.encrypted.length;
+    _emit(progress, {
+      phase: "encrypted",
+      relativePath: entry.relativePath,
+      encryptedSize: encResult.encrypted.length,
+    });
+  }
+
+  if (fileEntries.length === 0) {
+    // Nothing to write; refuse to emit an empty manifest. Operators
+    // who genuinely want an "empty backup" need to revisit their
+    // include list.
+    throw new BackupBundleError("backup-bundle/empty",
+      "create: no files included in bundle (every entry was missing or skipped)");
+  }
+
+  // 3. Build the manifest and write it last (so a half-written bundle
+  // can be detected by absence of manifest.json — an integrity tell)
+  _emit(progress, { phase: "write_manifest" });
+  var manifest = backupManifest.create({
+    vaultKeySalt: wrappedVk.salt,
+    vaultKeyEnc:  wrappedVk.encrypted.toString("base64"),
+    files:        fileEntries,
+    metadata:     opts.metadata || undefined,
+  });
+  var manifestPath = path.join(outDir, "manifest.json");
+  atomicFile.writeSync(manifestPath, backupManifest.serialize(manifest), { fileMode: 0o600 });
+
+  var durationMs = Date.now() - t0;
+  _emit(progress, {
+    phase: "done",
+    fileCount: fileEntries.length,
+    bundleSize: totalBytes,
+    durationMs: durationMs,
+  });
+  return {
+    manifest:     manifest,
+    manifestPath: manifestPath,
+    outDir:       outDir,
+    bundleSize:   totalBytes,
+    fileCount:    fileEntries.length,
+    durationMs:   durationMs,
+  };
+}
+
+module.exports = {
+  create:             create,
+  BackupBundleError:  BackupBundleError,
+};