@blamejs/core 0.4.1

package/lib/render.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Response helpers — render a value into an HTTP response with the
+ * right Content-Type, status, and body shape, in one call.
+ *
+ * Without these helpers every route handler reimplements the same
+ * five lines: pick a status code, set Content-Type, JSON.stringify
+ * (or render a template), set Content-Length, end the response. With
+ * them, each response shape is a single call:
+ *
+ *   render.json(res, { ok: true })
+ *   render.text(res, "OK")
+ *   render.redirect(res, "/login")
+ *   render.htmlString(res, "<h1>Hi</h1>")
+ *   r.html(res, "home", { user: req.user })   // engine-bound (see create())
+ *
+ * The template engine isn't required to use any of the non-HTML
+ * helpers. Operators who never render server-side HTML just import
+ * the module-level json/text/redirect.
+ *
+ * Public API:
+ *
+ *   render.json(res, body, opts?)
+ *     → JSON-stringifies body, sets Content-Type application/json;
+ *       opts.status (default 200) + opts.headers merged.
+ *
+ *   render.text(res, body, opts?)
+ *     → text/plain. opts.status / opts.headers / opts.charset (default utf-8).
+ *
+ *   render.htmlString(res, htmlString, opts?)
+ *     → text/html for a pre-rendered string; same opts shape.
+ *
+ *   render.redirect(res, location, opts?)
+ *     → opts.status (default 302; 301/303/307/308 also valid).
+ *       Location is set; body empty.
+ *
+ *   render.create({ engine }) → {
+ *     html(res, viewName, data?, opts?)         engine-rendered HTML
+ *     json, text, htmlString, redirect          re-exported for one-import ergonomics
+ *   }
+ *     engine is a template engine instance from
+ *     b.template.create({ viewsDir }). html() throws if rendering
+ *     fails — wire b.middleware.errorHandler downstream to convert
+ *     to a sanitized 500 response.
+ *
+ * All helpers fall through silently when res is already finished
+ * (`writableEnded === true`). Mid-stream double-writes from a route
+ * that already sent a response (e.g. a Promise rejection after
+ * res.end) won't corrupt the wire.
+ */
+
+var DEFAULT_CHARSET = "utf-8";
+
+function _alreadyDone(res) {
+  return res && res.writableEnded === true;
+}
+
+function _writeResponse(res, status, headers, body) {
+  if (_alreadyDone(res)) return;
+  if (typeof res.writeHead === "function") {
+    res.writeHead(status, headers);
+  } else {
+    // Plain object response (for tests). Best-effort header set.
+    res.statusCode = status;
+    if (typeof res.setHeader === "function") {
+      for (var k in headers) {
+        if (Object.prototype.hasOwnProperty.call(headers, k)) res.setHeader(k, headers[k]);
+      }
+    }
+  }
+  if (typeof res.end === "function") res.end(body);
+}
+
+function _mergedHeaders(base, extra) {
+  if (!extra) return base;
+  var out = {};
+  for (var k in base)  { if (Object.prototype.hasOwnProperty.call(base,  k)) out[k] = base[k]; }
+  for (var j in extra) { if (Object.prototype.hasOwnProperty.call(extra, j)) out[j] = extra[j]; }
+  return out;
+}
+
+// Default Cache-Control for dynamic responses. Browsers heuristically
+// cache HTML responses without explicit headers, which causes "saved
+// changes don't appear" bugs after a POST/redirect. `no-cache` permits
+// caching but forces revalidation on every access — server returns 200
+// with fresh content (or 304 if unchanged) instead of the browser
+// silently serving stale. Operators wanting a public CDN cacheable
+// response override via `opts.headers["Cache-Control"]`.
+var DEFAULT_DYNAMIC_CACHE_CONTROL = "private, no-cache, must-revalidate";
+
+function json(res, body, opts) {
+  opts = opts || {};
+  var encoded = JSON.stringify(body);
+  var headers = _mergedHeaders({
+    "Content-Type":   "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(encoded, "utf8"),
+    "Cache-Control":  DEFAULT_DYNAMIC_CACHE_CONTROL,
+  }, opts.headers);
+  _writeResponse(res, opts.status || 200, headers, encoded);
+}
+
+function text(res, body, opts) {
+  opts = opts || {};
+  var encoded = body == null ? "" : String(body);
+  var charset = opts.charset || DEFAULT_CHARSET;
+  var headers = _mergedHeaders({
+    "Content-Type":   "text/plain; charset=" + charset,
+    "Content-Length": Buffer.byteLength(encoded, charset),
+    "Cache-Control":  DEFAULT_DYNAMIC_CACHE_CONTROL,
+  }, opts.headers);
+  _writeResponse(res, opts.status || 200, headers, encoded);
+}
+
+function htmlString(res, htmlBody, opts) {
+  opts = opts || {};
+  var encoded = htmlBody == null ? "" : String(htmlBody);
+  var charset = opts.charset || DEFAULT_CHARSET;
+  var headers = _mergedHeaders({
+    "Content-Type":   "text/html; charset=" + charset,
+    "Content-Length": Buffer.byteLength(encoded, charset),
+    "Cache-Control":  DEFAULT_DYNAMIC_CACHE_CONTROL,
+  }, opts.headers);
+  _writeResponse(res, opts.status || 200, headers, encoded);
+}
+
+function redirect(res, location, opts) {
+  opts = opts || {};
+  if (typeof location !== "string" || location.length === 0) {
+    throw new Error("render.redirect: location is required");
+  }
+  var status = opts.status || 302;
+  if (status < 300 || status > 399) {
+    throw new Error("render.redirect: status must be 3xx (got " + status + ")");
+  }
+  var headers = _mergedHeaders({
+    "Location":       location,
+    "Content-Length": 0,
+    "Cache-Control":  DEFAULT_DYNAMIC_CACHE_CONTROL,
+  }, opts.headers);
+  _writeResponse(res, status, headers, "");
+}
+
+// ---- Engine-bound instance ----
+
+function create(opts) {
+  opts = opts || {};
+  if (!opts.engine || typeof opts.engine.render !== "function") {
+    throw new Error("render.create({ engine }): engine.render must be a function " +
+      "(pass a template engine from b.template.create)");
+  }
+  var engine = opts.engine;
+
+  function html(res, viewName, data, htmlOpts) {
+    htmlOpts = htmlOpts || {};
+    // Auto-merge res.locals into template data — the framework's
+    // request-scoped surface (cspNonce, requestId, current user, etc.)
+    // lands in res.locals via middleware (csp-nonce, attach-user, etc.).
+    // Operators no longer have to thread these through every render
+    // call. Operator-supplied `data` keys take precedence over locals
+    // — explicit > implicit.
+    var merged;
+    if (res && res.locals && typeof res.locals === "object") {
+      merged = {};
+      var lk = Object.keys(res.locals);
+      for (var li = 0; li < lk.length; li++) merged[lk[li]] = res.locals[lk[li]];
+      if (data) {
+        var dk = Object.keys(data);
+        for (var di = 0; di < dk.length; di++) merged[dk[di]] = data[dk[di]];
+      }
+    } else {
+      merged = data || {};
+    }
+    var body = engine.render(viewName, merged);
+    return htmlString(res, body, htmlOpts);
+  }
+
+  return {
+    html:        html,
+    htmlString:  htmlString,
+    json:        json,
+    text:        text,
+    redirect:    redirect,
+    engine:      engine,
+  };
+}
+
+module.exports = {
+  create:      create,
+  json:        json,
+  text:        text,
+  htmlString:  htmlString,
+  redirect:    redirect,
+};

package/lib/request-helpers.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * request-helpers — small shared utilities for HTTP request middleware.
+ *
+ * The framework's metrics + tracing requestMiddleware both label by
+ * route TEMPLATE and capture the final response status. They had
+ * identical implementations of:
+ *
+ *   1. Reading req.routePattern with a URL-fallback
+ *   2. Wrapping res.writeHead + reading res.statusCode at res.end
+ *
+ * This module owns the two helpers so the duplication doesn't drift —
+ * if either pattern changes (e.g. handle res.statusMessage), it changes
+ * once.
+ *
+ * Public API:
+ *
+ *   resolveRoute(req)
+ *     Returns req.routePattern when the router populated it,
+ *     otherwise the URL with query string stripped.
+ *
+ *   captureResponseStatus(res, onEnd)
+ *     Wraps res.writeHead + res.end. Calls onEnd(status) once when the
+ *     response ends, with the final status pulled from writeHead's
+ *     argument OR from res.statusCode (modern Node handlers set it
+ *     directly without going through writeHead). Operators wrap their
+ *     own pre-end logic by passing it as onEnd.
+ *
+ *     Returns the original (unwrapped) `res.end`. Useful for unit tests
+ *     that need to assert against the original behavior.
+ */
+
+// extractActorContext(req) — pull the 5 W's from a request for audit
+// chain emission. WHO/WHERE/HOW columns on _blamejs_audit_log are
+// populated from this shape:
+//
+//   { ip, userAgent, sessionId, requestId, method, route, userId }
+//
+// Every field is best-effort: missing or non-request inputs return
+// an object with whatever could be inferred plus null elsewhere.
+// Audit chain treats null as "unknown", so partial context is safe.
+//
+// Caller-supplied actor (existing actor.userId, actor.ip, etc.) is
+// merged on top of the request-derived fields — explicit operator
+// override always wins.
+function extractActorContext(req, override) {
+  var ctx = {
+    ip:        null,
+    userAgent: null,
+    sessionId: null,
+    requestId: null,
+    method:    null,
+    route:     null,
+    userId:    null,
+  };
+  if (req && typeof req === "object") {
+    // Direct properties first (Express-shaped frameworks set req.ip).
+    if (typeof req.ip === "string") ctx.ip = req.ip;
+    else if (req.connection && typeof req.connection.remoteAddress === "string") {
+      ctx.ip = req.connection.remoteAddress;
+    } else if (req.socket && typeof req.socket.remoteAddress === "string") {
+      ctx.ip = req.socket.remoteAddress;
+    }
+    if (req.headers && typeof req.headers["user-agent"] === "string") {
+      ctx.userAgent = req.headers["user-agent"];
+    }
+    if (req.session && typeof req.session.id === "string") ctx.sessionId = req.session.id;
+    else if (typeof req.sessionId === "string") ctx.sessionId = req.sessionId;
+    if (typeof req.requestId === "string") ctx.requestId = req.requestId;
+    else if (req.headers && typeof req.headers["x-request-id"] === "string") {
+      ctx.requestId = req.headers["x-request-id"];
+    }
+    if (typeof req.method === "string") ctx.method = req.method;
+    ctx.route = resolveRoute(req);
+    // userId from common shapes the framework's auth surfaces produce
+    if (req.user && typeof req.user.id === "string") ctx.userId = req.user.id;
+    else if (req.user && typeof req.user.userId === "string") ctx.userId = req.user.userId;
+    else if (req.apiKey && typeof req.apiKey.ownerId === "string") ctx.userId = req.apiKey.ownerId;
+  }
+  if (override && typeof override === "object") {
+    for (var k in override) {
+      if (Object.prototype.hasOwnProperty.call(override, k) && override[k] != null) {
+        ctx[k] = override[k];
+      }
+    }
+  }
+  return ctx;
+}
+
+function resolveRoute(req) {
+  if (req && typeof req.routePattern === "string" && req.routePattern.length > 0) {
+    return req.routePattern;
+  }
+  var url = req && req.url;
+  if (typeof url !== "string" || url.length === 0) return "/";
+  var qIdx = url.indexOf("?");
+  return qIdx === -1 ? url : url.slice(0, qIdx);
+}
+
+function captureResponseStatus(res, onEnd) {
+  if (!res || typeof onEnd !== "function") {
+    throw new Error("captureResponseStatus: requires (res, onEnd)");
+  }
+  var origEnd = res.end;
+  var origWriteHead = res.writeHead;
+  var statusFromWriteHead = null;
+  res.writeHead = function (s) {
+    statusFromWriteHead = s;
+    return origWriteHead.apply(res, arguments);
+  };
+  res.end = function () {
+    var status = statusFromWriteHead != null
+                   ? statusFromWriteHead
+                   : (typeof res.statusCode === "number" ? res.statusCode : 200);
+    try { onEnd(status); }
+    catch (_e) { /* onEnd never breaks the response — caller's instrumentation issue */ }
+    return origEnd.apply(res, arguments);
+  };
+  return origEnd;
+}
+
+// parseQualityList — RFC 9110 §12.5 Accept-* header parser.
+//
+// Returns `[{ value, q }]` sorted by q descending. Used by content
+// negotiation (`Accept-Encoding`, `Accept-Language`, `Accept`, etc.).
+// Each Accept-* middleware previously had its own copy of this loop;
+// extracting it here keeps the q-value semantics consistent
+// (q=0 = explicit exclusion; clamped to [0, 1]; missing q = 1).
+//
+//   parseQualityList("br;q=1.0, gzip;q=0.5, *;q=0")
+//     → [{ value: "br", q: 1 }, { value: "gzip", q: 0.5 }, { value: "*", q: 0 }]
+//
+// `value` is lowercased by default; pass `{ caseSensitive: true }` to
+// preserve case (BCP 47 language tags want case preservation since
+// `pt-BR` and `pt-br` resolve identically but operators may match by
+// canonical form themselves).
+//
+// Bad input (non-string, empty) returns []. RFC 9110 says an absent
+// Accept header means "accept anything"; callers handle that absence
+// at their own layer (compression's [{ encoding: "*", q: 1 }] default
+// vs i18n's "fall back to default locale" — different semantics).
+var Q_VALUE_RE = /(?:^|;|\s)q\s*=\s*([0-9]*\.?[0-9]+)/i;
+
+function parseQualityList(headerValue, opts) {
+  if (typeof headerValue !== "string" || headerValue.length === 0) return [];
+  opts = opts || {};
+  var caseSensitive = opts.caseSensitive === true;
+  var parts = headerValue.split(",");
+  var out = [];
+  for (var i = 0; i < parts.length; i++) {
+    var p = parts[i].trim();
+    if (p.length === 0) continue;
+    var semi = p.indexOf(";");
+    var value, q;
+    if (semi === -1) {
+      value = caseSensitive ? p : p.toLowerCase();
+      q = 1;
+    } else {
+      var head = p.slice(0, semi).trim();
+      value = caseSensitive ? head : head.toLowerCase();
+      var rest = p.slice(semi + 1).trim();
+      var qm = rest.match(Q_VALUE_RE);
+      q = qm ? parseFloat(qm[1]) : 1;
+      if (isNaN(q) || q < 0) q = 0;
+      if (q > 1) q = 1;
+    }
+    out.push({ value: value, q: q });
+  }
+  out.sort(function (a, b) { return b.q - a.q; });
+  return out;
+}
+
+module.exports = {
+  resolveRoute:          resolveRoute,
+  captureResponseStatus: captureResponseStatus,
+  extractActorContext:   extractActorContext,
+  parseQualityList:      parseQualityList,
+};

package/lib/restore-bundle.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * restore-bundle — extract an encrypted backup bundle to a staging dir.
+ *
+ * The mirror of backup-bundle. Reads manifest.json from a bundle
+ * directory, decrypts each per-file blob via backup-crypto, verifies
+ * each plaintext's sha3-512 checksum matches the manifest, and writes
+ * the recovered files to a staging directory the caller then atomically
+ * swaps into place. The bundle directory itself is read-only throughout.
+ *
+ *   var r = await b.restoreBundle.extract({
+ *     bundleDir:    "./backups/2026-04-27.bundle",
+ *     stagingDir:   "./data.staging",       // must NOT exist
+ *     passphrase:   Buffer.from("operator passphrase"),
+ *     filter:       function (entry) { return true; },  // optional
+ *     progressCallback: function (event) { ... },
+ *   });
+ *   // → { manifest, vaultKeyJson, fileCount, totalBytes,
+ *   //     stagingDir, durationMs }
+ *
+ * vaultKeyJson is the decrypted vault keypair JSON the bundle carried
+ * in manifest.vaultKeyEnc. The caller decides what to do with it:
+ * write to stagingDir/vault.key for a fresh framework boot, hand to
+ * vault.init for an in-process load, etc. — restore-bundle's job ends
+ * at recovery; vault-key placement is operator policy.
+ *
+ * filter: optional predicate that lets a caller pull a subset (only
+ * the DB, only the TLS keys, etc.). The vault key is always recovered
+ * regardless of filter so the operator can read sealed values from a
+ * partial restore.
+ *
+ * Defense:
+ *   - Wrong passphrase → AEAD tag check fails on first blob →
+ *     restore-bundle/decrypt-failed (no plaintext leaked, no staging
+ *     left behind)
+ *   - Tampered blob (single byte flip in ciphertext) → same path
+ *   - encryptedSize mismatch → restore-bundle/size-mismatch (cheap
+ *     pre-decrypt check)
+ *   - Plaintext sha3-512 != manifest.checksum → restore-bundle/
+ *     checksum-mismatch (post-decrypt integrity guard)
+ *   - Missing blob file → restore-bundle/missing-blob (manifest
+ *     references a path the bundle dir doesn't have)
+ *   - On any failure, the partially-built stagingDir is removed so a
+ *     subsequent retry isn't blocked by a stale dir
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("./atomic-file");
+var backupCrypto = require("./backup/crypto");
+var backupManifest = require("./backup/manifest");
+var { defineClass } = require("./framework-error");
+
+var RestoreBundleError = defineClass("RestoreBundleError", { alwaysPermanent: true });
+
+function _emit(cb, ev) {
+  if (typeof cb === "function") {
+    try { cb(ev); } catch (_e) { /* progress-callback errors are non-fatal */ }
+  }
+}
+
+function _cleanupStaging(stagingDir) {
+  // Best-effort recursive remove — if cleanup fails, surface that to
+  // the caller via stderr but never override the original error
+  // we're already throwing.
+  try { fs.rmSync(stagingDir, { recursive: true, force: true }); }
+  catch (_e) { /* best-effort */ }
+}
+
+async function extract(opts) {
+  var t0 = Date.now();
+  opts = opts || {};
+  if (typeof opts.bundleDir !== "string" || !fs.existsSync(opts.bundleDir)) {
+    throw new RestoreBundleError("restore-bundle/no-bundle",
+      "extract: opts.bundleDir is required and must exist");
+  }
+  if (typeof opts.stagingDir !== "string" || opts.stagingDir.length === 0) {
+    throw new RestoreBundleError("restore-bundle/no-staging",
+      "extract: opts.stagingDir is required");
+  }
+  if (fs.existsSync(opts.stagingDir)) {
+    throw new RestoreBundleError("restore-bundle/staging-exists",
+      "extract: stagingDir already exists: " + opts.stagingDir +
+      " (refusing to merge into existing directory — pick a fresh path)");
+  }
+  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
+    throw new RestoreBundleError("restore-bundle/no-passphrase",
+      "extract: opts.passphrase is required (Buffer or string)");
+  }
+  var passphrase = opts.passphrase;
+  var bundleDir = opts.bundleDir;
+  var stagingDir = opts.stagingDir;
+  var filter = typeof opts.filter === "function" ? opts.filter : null;
+  var progress = opts.progressCallback;
+
+  // 1. Read + parse + validate manifest
+  _emit(progress, { phase: "read_manifest" });
+  var manifestPath = path.join(bundleDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new RestoreBundleError("restore-bundle/missing-manifest",
+      "extract: bundleDir has no manifest.json — bundle is incomplete or not a blamejs backup");
+  }
+  var manifest;
+  try {
+    manifest = backupManifest.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    if (e && e.isBackupManifestError) throw e;
+    throw new RestoreBundleError("restore-bundle/bad-manifest",
+      "extract: manifest could not be parsed: " + ((e && e.message) || String(e)));
+  }
+
+  // 2. Recover the vault key (always, regardless of filter — the
+  // operator may need it to unseal post-restore even on partial
+  // restores)
+  _emit(progress, { phase: "unwrap_vault_key" });
+  var vaultKeyJson;
+  try {
+    var vkBuf = await backupCrypto.decryptWithPassphrase(
+      Buffer.from(manifest.vaultKeyEnc, "base64"),
+      passphrase,
+      manifest.vaultKeySalt);
+    vaultKeyJson = vkBuf.toString("utf8");
+  } catch (e) {
+    if (e && e.isBackupCryptoError && e.code === "backup-crypto/decrypt-failed") {
+      throw new RestoreBundleError("restore-bundle/decrypt-failed",
+        "extract: passphrase rejected (vault key did not decrypt). " +
+        "If you have multiple backup passphrases, double-check the one supplied.");
+    }
+    throw new RestoreBundleError("restore-bundle/vault-key-recovery-failed",
+      "extract: could not recover vault key from manifest: " + ((e && e.message) || String(e)));
+  }
+
+  atomicFile.ensureDir(stagingDir);
+
+  // 3. Walk manifest.files; decrypt + verify + write each that passes filter
+  var fileCount = 0;
+  var totalBytes = 0;
+
+  try {
+    for (var i = 0; i < manifest.files.length; i++) {
+      var entry = manifest.files[i];
+      if (filter && !filter(entry)) {
+        _emit(progress, { phase: "skip_filtered", relativePath: entry.relativePath });
+        continue;
+      }
+
+      var blobPath = path.join(bundleDir, entry.encryptedPath);
+      if (!fs.existsSync(blobPath)) {
+        throw new RestoreBundleError("restore-bundle/missing-blob",
+          "extract: manifest references '" + entry.encryptedPath +
+          "' but the bundle has no such file");
+      }
+      var blob = fs.readFileSync(blobPath);
+      if (blob.length !== entry.encryptedSize) {
+        throw new RestoreBundleError("restore-bundle/size-mismatch",
+          "extract: blob '" + entry.encryptedPath + "' has size " + blob.length +
+          " but manifest expected " + entry.encryptedSize);
+      }
+
+      _emit(progress, {
+        phase: "decrypt", relativePath: entry.relativePath,
+        encryptedSize: entry.encryptedSize,
+      });
+
+      var plaintext;
+      try {
+        plaintext = await backupCrypto.decryptWithPassphrase(blob, passphrase, entry.salt);
+      } catch (e) {
+        if (e && e.isBackupCryptoError && e.code === "backup-crypto/decrypt-failed") {
+          throw new RestoreBundleError("restore-bundle/decrypt-failed",
+            "extract: blob '" + entry.encryptedPath + "' did not decrypt — " +
+            "passphrase rejected or ciphertext tampered");
+        }
+        throw e;
+      }
+      if (plaintext.length !== entry.size) {
+        throw new RestoreBundleError("restore-bundle/size-mismatch",
+          "extract: decrypted '" + entry.relativePath +
+          "' has " + plaintext.length + " bytes but manifest expected " + entry.size);
+      }
+      var actualChecksum = backupCrypto.checksum(plaintext);
+      if (actualChecksum !== entry.checksum) {
+        throw new RestoreBundleError("restore-bundle/checksum-mismatch",
+          "extract: decrypted '" + entry.relativePath + "' has checksum " + actualChecksum +
+          " but manifest declared " + entry.checksum +
+          " — bundle is corrupted or manifest tampered");
+      }
+
+      var destPath = path.join(stagingDir, entry.relativePath);
+      atomicFile.ensureDir(path.dirname(destPath));
+      atomicFile.writeSync(destPath, plaintext, { fileMode: 0o600 });
+
+      fileCount++;
+      totalBytes += plaintext.length;
+    }
+  } catch (e) {
+    _cleanupStaging(stagingDir);
+    throw e;
+  }
+
+  var durationMs = Date.now() - t0;
+  _emit(progress, {
+    phase: "done",
+    fileCount: fileCount,
+    totalBytes: totalBytes,
+    durationMs: durationMs,
+  });
+  return {
+    manifest:     manifest,
+    vaultKeyJson: vaultKeyJson,
+    fileCount:    fileCount,
+    totalBytes:   totalBytes,
+    stagingDir:   stagingDir,
+    durationMs:   durationMs,
+  };
+}
+
+// Inspect a bundle without decrypting — read the manifest and return
+// it. Useful for dashboards and pre-flight UI: list files, sizes,
+// timestamps, kinds without prompting for the passphrase.
+function inspect(opts) {
+  opts = opts || {};
+  if (typeof opts.bundleDir !== "string" || !fs.existsSync(opts.bundleDir)) {
+    throw new RestoreBundleError("restore-bundle/no-bundle",
+      "inspect: opts.bundleDir is required and must exist");
+  }
+  var manifestPath = path.join(opts.bundleDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new RestoreBundleError("restore-bundle/missing-manifest",
+      "inspect: bundleDir has no manifest.json");
+  }
+  return backupManifest.parse(fs.readFileSync(manifestPath, "utf8"));
+}
+
+module.exports = {
+  extract:             extract,
+  inspect:             inspect,
+  RestoreBundleError:  RestoreBundleError,
+};